# Readme > | - **Type:** Skill - **Install:** `agentstack add skill-jesamkim-oh-my-skills-readme` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [jesamkim](https://agentstack.voostack.com/s/jesamkim) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [jesamkim](https://github.com/jesamkim) - **Source:** https://github.com/jesamkim/oh-my-skills/tree/main/my-skills/readme ## Install ```sh agentstack add skill-jesamkim-oh-my-skills-readme ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # README Craft - Professional README Generator Create READMEs that make people stop scrolling and start reading. A great README is the front door to your project. It should communicate what the project does, why it matters, and how to get started -- all within 30 seconds of landing on the page. ## Quick Start 1. Read [references/structure.md](references/structure.md) for README structure patterns 2. Read [references/badges.md](references/badges.md) for badge creation 3. Read [references/visual-elements.md](references/visual-elements.md) for visual asset guidance ## Core Philosophy Tom Preston-Werner said it best: "Write the README first." A README is not an afterthought -- it is the single most important document in your repository. It frames the project for every person who encounters it: users, contributors, hiring managers, and your future self. The goal is not decoration. The goal is **clarity at a glance**. Every element you add (logo, badge, GIF, diagram) should reduce the time it takes someone to understand what this project does and whether they need it. ## Workflow ### Step 1: Understand the Project Before writing anything, gather context: - What does this project do? (one sentence) - Who is the target audience? (developers, data scientists, end users, internal team) - What is the project type? (library, CLI tool, web app, API, framework, infrastructure) - What language/framework does it use? - Is it open-source or internal? - Does it have a logo or visual identity? If you have access to the codebase, scan the project structure, package.json (or equivalent), and any existing documentation to extract this information. ### Step 2: Choose the Right Structure Select a structure pattern from [references/structure.md](references/structure.md) based on project type. The core sections every README needs: 1. **Header** -- Logo/banner + project name + one-line description 2. **Badges** -- Build status, version, license, coverage (see [references/badges.md](references/badges.md)) 3. **Visual Demo** -- Screenshot, GIF, or diagram showing the project in action 4. **What & Why** -- What problem does it solve? Why should someone care? 5. **Quick Start** -- Fastest path from zero to working (under 5 commands) 6. **Usage** -- Code examples for the most common use cases 7. **API / Configuration** -- Reference documentation (if applicable) 8. **Architecture** -- High-level diagram for complex projects 9. **Contributing** -- How to help (link to CONTRIBUTING.md for details) 10. **License** -- Clear license statement ### Step 3: Craft the Header The header is the most important visual element. It sets the tone. **Logo placement:** ```markdown Project Name One compelling sentence that explains what this does. ``` **Banner style** (for projects with strong visual identity): ```markdown ``` The one-line description is critical. It should answer: "What is this?" without requiring any prior context. Write it like a dictionary definition, not a marketing tagline. Good: "A fast, lightweight key-value store written in Go" Bad: "The next-generation solution for your data needs" ### Step 4: Add Badges Badges provide instant credibility and project health signals. Use [references/badges.md](references/badges.md) for the complete guide. Place badges right after the header, centered: ```markdown [](link) [](link) [](link) [](link) ``` **Badge priority order** (include what's relevant, skip what's not): 1. Build/CI status -- proves the project works 2. Version/Release -- shows active maintenance 3. License -- answers legal questions immediately 4. Test coverage -- signals code quality 5. Downloads/Stars -- social proof 6. Language/Framework -- quick tech identification ### Step 5: Visual Demo A picture is worth a thousand words. A GIF is worth ten thousand. **For CLI tools:** Use terminal recording GIFs (vhs, terminalizer, or asciinema) **For web apps:** Screenshot of the main interface, or a short GIF of the key workflow **For libraries:** Code snippet + output screenshot side by side **For APIs:** Show a request/response example with syntax highlighting ```markdown ``` See [references/visual-elements.md](references/visual-elements.md) for tools and techniques for creating compelling visual assets. ### Step 6: Write the Content **Installation section:** - Show the simplest install path first - Use tabbed code blocks if multiple package managers are supported - Include prerequisites if any ```markdown ## Installation ```bash npm install my-package ``` Or with yarn: ```bash yarn add my-package ``` ``` **Usage section:** - Start with the simplest possible example - Progress to more complex use cases - Every code block should be copy-pasteable and runnable **Architecture section** (for complex projects): - Use Mermaid diagrams when possible (GitHub renders them natively) - Keep diagrams high-level; link to detailed docs for depth - Show data flow, not just component boxes ### Step 7: Table of Contents For READMEs longer than 3 screen-heights, add a TOC after the badges: ```markdown ## Table of Contents - [Installation](#installation) - [Quick Start](#quick-start) - [Usage](#usage) - [Configuration](#configuration) - [Architecture](#architecture) - [Contributing](#contributing) - [License](#license) ``` For shorter READMEs, skip the TOC. It adds noise without value. ### Step 8: Polish - Use consistent heading levels (H2 for main sections, H3 for subsections) - Add horizontal rules (`---`) sparingly to separate major sections - Use `` tags for optional/advanced content that would clutter the main flow - End with a clear license statement and optionally a "Made with" or credits section - Check all links work - Verify images render at reasonable sizes ## Project Type Adaptations **Open-source library:** Emphasize installation, API docs, code examples, and contributing guide. Badge priority: version, build, coverage, license, downloads. **CLI tool:** Lead with a GIF demo. Focus on install, basic commands, and configuration. Badge priority: version, build, license, platform support. **Web application:** Lead with a screenshot. Include deploy buttons (Vercel, Heroku, etc.) if applicable. Focus on features, setup, and environment variables. **Internal/corporate project:** Skip badges. Focus on setup, architecture, team conventions, and deployment procedures. Include links to related internal docs. **API:** Lead with a request/response example. Include authentication setup, endpoint reference, and rate limits. Consider linking to interactive API docs (Swagger/OpenAPI). ## Output Quality Checklist Before delivering the README, verify: - [ ] One-line description answers "what is this?" without jargon - [ ] Someone can go from zero to running in under 2 minutes with the Quick Start - [ ] All code blocks are syntax-highlighted and copy-pasteable - [ ] Visual assets (screenshots, GIFs) are present and render correctly - [ ] Badges are relevant (not decorative padding) - [ ] No broken links - [ ] License is clearly stated - [ ] Consistent formatting throughout - [ ] No walls of text -- information is scannable - [ ] README works well in both light and dark GitHub themes ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [jesamkim](https://github.com/jesamkim) - **Source:** [jesamkim/oh-my-skills](https://github.com/jesamkim/oh-my-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-jesamkim-oh-my-skills-readme - Seller: https://agentstack.voostack.com/s/jesamkim - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.