Generate compelling, well-structured README files following awesome-readme patterns. Analyzes project structure, extracts key information, and creates READMEs with progressive disclosure, visual elements, and beginner-friendly narratives. Use when creating a new project README, overhauling an existing one, or when a README feels stale or overwhelming.
/plugin marketplace add jrc1883/popkit-claude/plugin install popkit@popkit-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Generate professional, compelling README files that follow awesome-readme best practices. Creates READMEs with:
Announce at start: "I'm using the README builder skill to create/update your project's README."
Gather project context:
# Check package.json or similar
cat package.json 2>/dev/null | head -30
cat pyproject.toml 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -20
# Check existing README
cat README.md 2>/dev/null | head -50
# Check project structure
ls -la
ls src/ 2>/dev/null || ls lib/ 2>/dev/null
Extract:
Project Type:
Use AskUserQuestion tool with:
- question: "What type of project is this?"
- header: "Type"
- options:
- label: "CLI Tool"
description: "Command-line application"
- label: "Library/SDK"
description: "Reusable package for developers"
- label: "Web App"
description: "Website or web application"
- label: "Plugin"
description: "Extension for another platform"
- multiSelect: false
Target Audience:
Use AskUserQuestion tool with:
- question: "Who is the primary audience?"
- header: "Audience"
- options:
- label: "Beginners"
description: "New developers, needs hand-holding"
- label: "Intermediate"
description: "Knows basics, needs clear docs"
- label: "Advanced"
description: "Experts, wants concise reference"
- label: "Mixed"
description: "All skill levels"
- multiSelect: false
Visual Style:
Use AskUserQuestion tool with:
- question: "What visual style do you prefer?"
- header: "Style"
- options:
- label: "Minimal (Recommended)"
description: "Badges, clean formatting, no heavy graphics"
- label: "Visual-rich"
description: "Banner, GIFs, diagrams"
- label: "Text-only"
description: "Pure markdown, no images"
- multiSelect: false
Based on project type, select appropriate structure:
CLI Tool Template:
1. Hero (name + badges + tagline)
2. Demo GIF/screenshot
3. Quick Install (one-liner)
4. Usage Examples (3 common commands)
5. All Commands (collapsible)
6. Configuration
7. FAQ (collapsible)
8. Contributing + License
Library Template:
1. Hero (name + badges + tagline)
2. Why This Library (value prop)
3. Install
4. Quick Start (code example)
5. API Reference (brief + link)
6. Examples (collapsible)
7. Contributing + License
Web App Template:
1. Hero (name + badges)
2. Screenshot/Demo
3. Features (bullet points)
4. Getting Started (local dev)
5. Deployment
6. Tech Stack
7. Contributing + License
Plugin Template:
1. Hero (platform badge + name)
2. What It Does (one paragraph)
3. Install (platform-specific)
4. Quick Start (3 commands)
5. Features/Commands
6. Configuration
7. FAQ
8. Contributing + License
For each section, follow these principles:
Hero Section:
<p align="center">
<img src="assets/logo.png" alt="Project Name" width="200">
</p>
<h1 align="center">Project Name</h1>
<p align="center">
<strong>One-line tagline that explains the value</strong>
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-X.Y.Z-blue" alt="Version">
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
</p>
Installation:
Quick Start:
Progressive Disclosure:
<details> for advanced content<details>
<summary><strong>Advanced Configuration</strong></summary>
[Detailed content here]
</details>
After generating README, list needed assets:
| Asset | Purpose | Suggested Tool |
|---|---|---|
| Logo | Brand identity | Figma, Canva, or text-based |
| Banner | Hero section | Same as logo |
| Demo GIF | Show functionality | asciinema, ScreenToGif, VHS |
| Architecture diagram | System overview | Mermaid, Excalidraw |
Output:
Assets Needed:
- [ ] Logo (optional): assets/logo.png
- [ ] Demo GIF (recommended): assets/demo.gif
- [ ] Badges: Auto-generated via shields.io
You can create the README now and add visuals later.
Write README:
# Backup existing if present
cp README.md README.md.backup 2>/dev/null
# Write new README (use Write tool)
Validate:
Offer next steps via AskUserQuestion:
Use AskUserQuestion tool with:
- question: "README created. What's next?"
- header: "Next Step"
- options:
- label: "Commit it"
description: "Save to git with commit message"
- label: "Create assets"
description: "Help me create the visual assets"
- label: "Review first"
description: "I'll review and get back to you"
- label: "Done"
description: "That's all for now"
- multiSelect: false
For projects with predictable structure, use AUTO-GEN markers:
<!-- AUTO-GEN:COMMANDS START -->
| Command | Description |
|---------|-------------|
...
<!-- AUTO-GEN:COMMANDS END -->
These can be updated by CI or doc-sync tools.
Study these for inspiration:
The skill produces:
README.md - The main README fileassets_needed.md (optional) - List of visual assets to createThis skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.