| name | scaffold-skill-repo |
| description | Scaffolds a properly structured agent skill GitHub repo. Walks through creating all required files: SKILL.md, README.md, AGENTS.md, CONTEXT.md, LICENSE, examples/, and references/. Use when the user wants to create a new skill repo, structure a skill for distribution, or says "create a skill repo", "scaffold a skill", "make a skill repo like nuwa-skill", "set up a skill for publishing".
|
Scaffold Skill Repo
Creates a well-structured skill GitHub repo following the Agent Skills protocol, compatible with Claude Code, Codex, Cursor, OpenCode, and 50+ runtimes.
Uses nuwa-skill as the exemplar reference.
Execution Workflow
Phase 1: Gather Requirements
Ask the user 3-4 quick questions:
- Skill name — kebab-case, short, descriptive (e.g.,
my-framework-lint)
- What does it do? — one-sentence capability (e.g., "Lints my-framework configs against best practices")
- When should it trigger? — keywords, file patterns, user phrases (e.g., "review my-framework config", "lint config", file
*.mfconfig)
- Canonical references? — URLs to docs/specs/papers the skill is based on (optional)
Create the directory immediately after gathering, so all generated files land inside it.
mkdir -p <skill-name>/{references,templates,examples}
Phase 2: SKILL.md
Write <skill-name>/SKILL.md.
Frontmatter
---
name: <kebab-case-skill-name>
description: >
<One-sentence capability statement>.
Use when <specific trigger list>.
---
Rules:
name must match the directory name exactlydescription is the only thing the agent sees when deciding to load — invest effort here
- First sentence: what capability the skill provides
- Second sentence starts with "Use when " and lists concrete triggers (user phrases, file patterns, task types)
- Max 1024 chars
Body
Start with a level-1 heading matching the human-readable skill name.
Sections to include (adapt to skill domain):
| Section | Purpose |
|---|
| Background / Philosophy | Why this skill exists, what principles it follows |
| Process / Workflow | Numbered phases the agent follows when loaded |
| Rules / Constraints | Hard rules the agent must follow |
| Anti-patterns | What NOT to do (with WRONG vs RIGHT examples) |
| Decision trees | Branching logic for different scenarios |
| Checklists | - [ ] steps at decision gate points |
| References | Links to bundled resource files for progressive disclosure |
Length guidance: 100-200 lines max. Split detailed content into bundled files linked from the main SKILL.md.
Phase 3: README.md
Write <skill-name>/README.md.
# <Skill Name>
[](LICENSE)
[](https://agentskills.io)
[](https://skills.sh)
**<One-line description>**
<2-3 sentence capability description>
## Install
```bash
npx skills add yinchuangsum/<skill-name>
Then ask your agent: "."
How It Works
<Brief overview of what the skill does, 2-3 paragraphs, possibly a workflow list>
License
MIT
Badge bar is the first thing people see — include at minimum:
- License: MIT
- Agent Skills: Standard
- skills.sh: Compatible
### Phase 4: AGENTS.md
Write `<skill-name>/AGENTS.md`.
```markdown
## Agent Skills
- Plan changes or resolve design ambiguity using `grill-with-docs` to challenge proposals against this repo's CONTEXT.md and canonical references.
This ensures future agents working on this skill repo use the right planning process.
Phase 5: CONTEXT.md
Write <skill-name>/CONTEXT.md.
Captures domain language and design decisions so agents working on this repo don't repeat the same discovery process:
# Context: <Skill Name>
## What This Is
<Brief description>
## Domain Language
<Key terms and their meanings specific to this skill>
## Design Decisions
<Notable decisions and why they were made>
## Canonical References
- <URL links to source docs>
Phase 6: References
If the skill is based on external documents (docs, papers, specs), add them to <skill-name>/references/.
- If the doc is short (<50 lines): copy it inline as a reference file
- If the doc is long or externally maintained: create a short file with links and key excerpts
Split SKILL.md content into bundled reference files when:
- SKILL.md exceeds 200 lines
- Content has distinct domains
- Advanced features are rarely needed
Link to bundled files with relative paths: See [details](details.md).
Phase 7: Examples
Add <skill-name>/examples/ with at least one correct usage example.
If the skill defines right/wrong patterns, include both:
examples/right.xx — correct usageexamples/wrong.xx — anti-patterns (with comments explaining why)
Phase 8: LICENSE
MIT. Use the standard MIT text.
Phase 9: Verification
Before presenting the result, check:
Repository Structure Template
<skill-name>/
├── README.md
├── SKILL.md
├── AGENTS.md
├── CONTEXT.md
├── LICENSE
├── references/ # Canonical source docs
│ └── <source>.md
├── templates/ # Reusable file skeletons (optional)
│ └── <name>.template
└── examples/ # Correct / anti-pattern usage
├── right.xx
└── wrong.xx
Exemplar: nuwa-skill — the reference implementation of a well-structured skill repo.
