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:

1. Skill name — kebab-case, short, descriptive (e.g., my-framework-lint)
2. What does it do? — one-sentence capability (e.g., "Lints my-framework configs against best practices")
3. When should it trigger? — keywords, file patterns, user phrases (e.g., "review my-framework config", "lint config", file *.mfconfig)
4. 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.

bash
mkdir -p <skill-name>/{references,templates,examples}

Phase 2: SKILL.md

Write <skill-name>/SKILL.md.

Frontmatter

yaml
---
name: <kebab-case-skill-name>
description: >
  <One-sentence capability statement>.
  Use when <specific trigger list>.
---

Rules:

• name must match the directory name exactly
• description 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.

markdown
# <Skill Name>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Standard-green)](https://agentskills.io)
[![skills.sh](https://img.shields.io/badge/skills.sh-Compatible-blue)](https://skills.sh)

**<One-line description>**

<2-3 sentence capability description>

## Install

npx skills add yinchuangsum/<skill-name>

Then ask your agent: "<trigger phrase examples>."

## 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:

markdown
# 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 usage
• examples/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:

• ] SKILL.md has YAML frontmatter with name and description
• ] name matches directory name
• ] description includes "Use when..." with concrete triggers
• ] SKILL.md under 200 lines (split into bundled files if needed)
• ] README.md has badge bar + install command + usage example
• ] AGENTS.md references grill-with-docs
• ] CONTEXT.md captures domain language and decisions
• ] No time-sensitive info (dates, version numbers)
• ] Consistent terminology throughout
• ] References one level deep only
• ] No secrets or API keys
• ] LICENSE present (MIT)

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.