메뉴
USE WHEN: create readme, write readme, improve readme, rewrite my readme, document a library/CLI/utility, build project docs, get more GitHub stars. Picks Story or Utility mode based on whether there's a real story behind the project.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | awesome-readme |
| description | USE WHEN: create readme, write readme, improve readme, rewrite my readme, document a library/CLI/utility, build project docs, get more GitHub stars. Picks Story or Utility mode based on whether there's a real story behind the project. |
Create GitHub READMEs that get stars by telling compelling stories — or clean utility docs when there's no story to tell.
Core philosophy: Match the README to the project. A story-driven framing only works when there's a real story (a pain point, a frustration, an insight). If the project is "just a utility," forcing a fake narrative reads as cheap and hurts trust. Use Project Mode to pick the right structure.
Before drafting, classify the project — either ask the user via AskUserQuestion, or detect from context (existing README, CLAUDE.md, scope of the codebase):
| Mode | When to use | Structure emphasis |
|---|---|---|
| Story (default when a real story exists) | The project solves a real pain point the author personally felt. There's a "before / after" narrative, an insight moment, or a strong opinion behind it. | Hook → Problem → Insight → Solution → Demo → Features → Quick Start → How It Works → The Story → Footer |
| Utility | The project is a single-purpose tool, library, or scaffold with no narrative reason for existing. Examples: a CLI wrapper, a small dependency, a code-gen template, an internal helper. | Hook (one line) → Visuals (diagrams, screenshots, GIFs) → Features → Quick Start → API/Usage → Examples → Footer. Skip the personal story section entirely. |
| Hybrid | Mostly utility, but a short paragraph of motivation makes it more relatable. | Utility structure + a single 2–3 sentence "Why" callout near the top — never a multi-paragraph narrative arc. |
Rule: Never invent a story that isn't there. If the user can't articulate a clear pain/insight when asked, default to Utility mode.
When unclear, the Create workflow asks: "Does this project have a real story behind it (a pain you felt, a frustration that drove the build, an opinion you want to defend), or is it a utility/tool with no narrative?"
When executing a workflow, output this notification:
Running the **WorkflowName** workflow from the **awesome-readme** skill...
| Workflow | Trigger | File |
|---|---|---|
| Create | "create readme", "write readme", "new readme" | workflows/Create.md |
| Improve | "improve readme", "make readme better", "more compelling" | workflows/Improve.md |
| Analyze | "analyze readme", "review readme", "readme feedback" | workflows/Analyze.md |
Mode-specific markdown templates live under references/:
references/story-skeleton.md — 10-section Story-mode markdown templates + checklistreferences/utility-skeleton.md — Utility-mode skeleton + anti-patterns + checklist + visual-generation guidanceRead the relevant reference only when the workflow points you there. This keeps context lean — Story-mode runs don't load the Utility skeleton, and vice versa.
README visuals route through the gpt-image-2 skill — first-class, default. Image 2 is the strongest current image model for diagrams that contain real labels (~99% text fidelity), and it runs on the user's existing ChatGPT Plus/Pro subscription via the local Codex CLI.
Prerequisite — image generation backend. This plugin assumes one of:
- The
gpt-image-2skill is installed AND the user has the Codex CLI logged in to a ChatGPT Plus/Pro plan with Image 2 entitlement (the default route this plugin documents). See agentspace-so/agent-skills/gpt-image-2 for install instructions.- A substitute image-generation skill the user has wired up (e.g., a Gemini-based generator that accepts a prompt + output path via
GEMINI_API_KEY). The workflows route by intent ("generate a diagram for the README"), so a different generator can stand in if you swap the invocation pattern inworkflows/Create.mdStep 5.- Skip image generation entirely — every workflow respects a "No, text only" answer to its visuals
AskUserQuestion. The README still ships, just without diagrams.
If neither (1) nor (2) is set up and the user picks "Yes, generate via gpt-image-2", the gen.sh call will exit non-zero (codes 3–7 for missing CLI / not logged in / quota refused). Surface the failing layer in one sentence and ask the user how to proceed. Do not silently fall back to a weaker model, DALL·E, Midjourney, an HTML mockup, or any "make do" route.
When a workflow needs an image, invoke the gpt-image-2 skill directly:
bash scripts/gen.sh \
--prompt "<descriptive prompt for the README element>" \
--out docs/<descriptive-name>.png
For reference-image conditioning (remix an existing logo, restyle a screenshot, etc.):
bash scripts/gen.sh \
--prompt "<remix instruction>" \
--ref /absolute/path/to/reference.png \
--out docs/<descriptive-name>.png
The script lives inside the gpt-image-2 skill's directory; the standard skill loader resolves it. Pass the user's prompt through raw — only polish wording when the user explicitly asks for it. After the image lands, display/attach it in the response; never stop at "saved to docs/x.png".
Starting points, not mandates. If the user gave you a specific prompt, pass it through raw.
| Element | Prompt shape |
|---|---|
| Hero banner / cover | "<project> README hero banner. <subject>. Embedded tagline reads: '<tagline>'." — let Image 2 render the text directly |
| Architecture diagram | "Architecture diagram for <project>. <A> connects to <B> via <C>. Excalidraw / hand-drawn style. Clear labels on each node." |
| Workflow illustration | "Workflow illustration: step 1 <X>, step 2 <Y>, step 3 <Z>. Numbered left-to-right flow with annotated arrows." |
| Comparison visual | "Side-by-side comparison: '<A>' vs '<B>'. Two columns, contrasting treatment, clear winner indicated." |
| Pack / feature icon | "Square icon for <feature>. Flat design, single accent color, no text." |
docs/ directory by default — never the skill's own folder, never a tmp path the user has to fish out later.Security-inspect an AI agent skill (your own or a third party's) with the skillspector CLI, then deliver a plain-English verdict report in chat (safe / caution / do-not-install, threat breakdown, top findings to check, file hotspots). Use whenever you want to vet, scan, audit, or sanity-check a skill before installing or trusting it, point at a skill repo/folder/zip and ask "is this safe?", say "inspect this skill", "scan this skill", "check this skill for malware", "skillspector", or share a GitHub link to a skill/agent and want to know the risk. Also use to re-read confusing skillspector output.
Security-inspect an AI agent skill (your own or a third party's) with the skillspector CLI, then deliver a plain-English verdict report in chat (safe / caution / do-not-install, threat breakdown, top findings to check, file hotspots). Use whenever Ossie wants to vet, scan, audit, or sanity-check a skill before installing or trusting it, points at a skill repo/folder/zip and asks "is this safe?", says "inspect this skill", "scan this skill", "check this skill for malware", "skillspector", or shares a GitHub link to a skill/agent and wants to know the risk. Also use to re-read confusing skillspector output.
Execute GitHub issues one at a time as vertical slices — fetch, branch, TDD, verify, PR, then the next. Use when the user says "ship issue", "resolve
Unified 3D printing pipeline for Bambu Lab printers. USE WHEN user says: print, 3d print, slice, slice this, make me, design a part, model this, STL, 3MF, MakerWorld, browse models, find me a model, printer status, check printer, what's printing, prepare for printing, generate 3MF, fit on one plate, multi-object plate, storage, organizer, mount, holder, bracket, gridfinity, or provides STL files, photos of things to design, or MakerWorld links. Covers design with OpenSCAD MCP, browsing MakerWorld with agent-browser, slicing STL to 3MF with the bundled OrcaSlicer-backed CLI, multi-plate arrangement, and printer control with Bambu MCP. This is the only skill for 3D-printing related work.
USE WHEN: dogfood, QA, exploratory test, find issues, bug hunt, test this app/site/platform, or review the quality of a web application. Systematically explores a web app in a real browser, finds bugs and UX issues, and produces a structured report with full reproduction evidence (step-by-step screenshots, repro GIFs when available, and detailed repro steps) so findings can be handed straight to the responsible team.
USE WHEN: check/audit/update/improve/fix CLAUDE.md or AGENTS.md, CLAUDE.md maintenance, AGENTS.md review, project memory optimization, agent documentation. Audits agent instruction files against modern harness engineering principles (leanness, discoverability, anti-staleness), then applies targeted improvements after approval.