# Scaffold Skill

> Scaffold a new skill inside speckit-pro (or another plugin in this marketplace). Creates skills/<name>/SKILL.md with valid YAML frontmatter, optionally mirrors under codex-skills/, then runs python3 tests/speckit-pro/run-all.py --layer 1 to verify. Triggers on "scaffold skill", "add a skill", "new speckit skill", "create skill in plugin".

- Skill: `racecraft-lab/scaffold-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add racecraft-lab/scaffold-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/racecraft-lab/scaffold-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: racecraft-lab (https://skillmd.com/u/racecraft-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/racecraft-lab/scaffold-skill

---


# scaffold-skill

Scaffolds a new skill in a marketplace plugin. Both user-invocable and Claude-invocable.

## Inputs to ask for

1. **Plugin** — which plugin (default: `speckit-pro`)
2. **Skill name** — kebab-case, e.g. `my-skill`
3. **Description** — one sentence with concrete trigger phrases (the description is what Claude matches on; vague descriptions = skill never fires)
4. **Codex mirror** — yes/no. If yes, also create under `codex-skills/<name>/SKILL.md`
5. **References / scripts** — does the skill need supporting files? Default: no (start minimal per CLAUDE.md "Simplest change" rule)

## What this creates

```
<plugin>/skills/<name>/
└── SKILL.md
```

With frontmatter:
```yaml
---
name: <name>
description: <description>
license: MIT
---
```

Optional Codex mirror:
```
<plugin>/codex-skills/<name>/
└── SKILL.md
```

Optional `references/` and `scripts/` subdirs (only if user said yes).

## Post-create

Always run from the repository root:
```console
python3 tests/speckit-pro/run-all.py --layer 1
```

If Codex mirror created, also run:
```console
python3 tests/speckit-pro/layer1-structural/validate-codex-skills.py
```

If either fails, fix the SKILL.md before reporting success.

## What this does NOT do

- Does not touch `marketplace.json` or `release-please-config.json` (skills don't have their own version; they live inside a plugin)
- Does not commit (use `plugin-publish` skill for that, or commit manually)
- Does not write skill body content — only the frontmatter scaffold. User fills in the body.

## Hard rules

- Frontmatter must have at minimum `name` and `description`
- `name` in frontmatter must match the directory name
- Description must include concrete trigger phrases — not just "Helps with X"
- Codex mirror must have identical `name` to the Claude Code skill