---
name: yinchuangsum/scaffold-skill-repo
source: https://app.decimal.ai/s/yinchuangsum-scaffold-skill-repo@1/SKILL.md
source_sha256: dab65f2822e5
---

# Scaffold Skill Repo

Creates a well-structured skill GitHub repo following the [Agent Skills](https://agentskills.io) protocol, compatible with Claude Code, Codex, Cursor, OpenCode, and 50+ runtimes.

Uses [nuwa-skill](https://github.com/alchaincyf/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

```bash
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](https://github.com/alchaincyf/nuwa-skill) — the reference implementation of a well-structured skill repo.