crafting-effective-readmes
This Claude Code skill helps writers create and refine README files by matching content and structure to specific audiences and project types. Use it when starting a new README, adding sections to existing documentation, updating stale content, or reviewing accuracy against current project state. The skill provides templates and guidance for open source projects, personal portfolios, internal team documentation, and configuration folders.
git clone --depth 1 https://github.com/softaworks/agent-toolkit /tmp/crafting-effective-readmes && cp -r /tmp/crafting-effective-readmes/skills/crafting-effective-readmes ~/.claude/skills/crafting-effective-readmesSKILL.md
# Crafting Effective READMEs ## Overview READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder. **Always ask:** Who will read this, and what do they need to know? ## Process ### Step 1: Identify the Task **Ask:** "What README task are you working on?" | Task | When | |------|------| | **Creating** | New project, no README yet | | **Adding** | Need to document something new | | **Updating** | Capabilities changed, content is stale | | **Reviewing** | Checking if README is still accurate | ### Step 2: Task-Specific Questions **Creating initial README:** 1. What type of project? (see Project Types below) 2. What problem does this solve in one sentence? 3. What's the quickest path to "it works"? 4. Anything notable to highlight? **Adding a section:** 1. What needs documenting? 2. Where should it go in the existing structure? 3. Who needs this info most? **Updating existing content:** 1. What changed? 2. Read current README, identify stale sections 3. Propose specific edits **Reviewing/refreshing:** 1. Read current README 2. Check against actual project state (package.json, main files, etc.) 3. Flag outdated sections 4. Update "Last reviewed" date if present ### Step 3: Always Ask After drafting, ask: **"Anything else to highlight or include that I might have missed?"** ## Project Types | Type | Audience | Key Sections | Template | |------|----------|--------------|----------| | **Open Source** | Contributors, users worldwide | Install, Usage, Contributing, License | `templates/oss.md` | | **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `templates/personal.md` | | **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `templates/internal.md` | | **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `templates/xdg-config.md` | **Ask the user** if unclear. Don't assume OSS defaults for everything. ## Essential Sections (All Types) Every README needs at minimum: 1. **Name** - Self-explanatory title 2. **Description** - What + why in 1-2 sentences 3. **Usage** - How to use it (examples help) ## References - `section-checklist.md` - Which sections to include by project type - `style-guide.md` - Common README mistakes and prose guidance - `using-references.md` - Guide to deeper reference materials
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
Use this agent when you need to visualize UI concepts through ASCII mockups before implementation. Examples: <example>Context: User has an idea for a dashboard layout with data tables and charts. user: 'I want to create a dashboard that shows user analytics with a sidebar navigation, main content area with charts, and a data table below' assistant: 'I'll use the ascii-ui-mockup-generator agent to create multiple ASCII mockup variations for your dashboard concept.' <commentary>The user wants to visualize a UI concept, so use the ascii-ui-mockup-generator to create multiple ASCII representations they can choose from.</commentary></example> <example>Context: User is designing a form layout with multiple input fields. user: 'I need a contact form with name, email, message fields and a submit button' assistant: 'Let me use the ascii-ui-mockup-generator to create several ASCII mockup options for your contact form layout.' <commentary>Since the user needs to visualize form layouts, use the ascii-ui-mockup-generator to provide multiple ASCII design options.</commentary></example>
Create API handoff documentation for frontend developers. Use when backend work is complete and needs to be documented for frontend integration, or user says 'create handoff', 'document API', 'frontend handoff', or 'API documentation'.
Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".
codebase-pattern-finder is a useful subagent_type for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details!
Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing. Uses GPT-5.2 by default for state-of-the-art software engineering.
Create a detailed implementation plan using Codex 5.2 with high reasoning
This skill should be used when creating a Claude Code slash command. Use when users ask to "create a command", "make a slash command", "add a command", or want to document a workflow as a reusable command. Essential for creating optimized, agent-executable slash commands with proper structure and best practices.