ai-scaffold

Scaffold

Purpose

Create new skills and agents for the ai-engineering framework. Owns the ai-engineering context layer (governance, manifest registration, IDE mirrors, pain sources). Delegates skill drafting, TDD pressure testing, eval pipeline, and description optimization to Anthropic's skill-creator.

Trigger

/ai-scaffold skill <name> or /ai-scaffold agent <name> — when the framework needs a new capability that no existing skill or agent covers.

---

Start Here — Registration Checklist

This is the invariant checklist that must be satisfied regardless of whether you're creating a skill or an agent. Write it at the top and check items off as you go:

## Registration Checklist — [NAME]
- [ ] No overlap with existing skills (checked skill list in manifest.yml)
- [ ] File created at correct path (.github/skills/ai-{name}/SKILL.md or .github/agents/{name}.agent.md)
- [ ] Frontmatter has name, description, argument-hint
- [ ] Description is CSO-optimized (triggering conditions, not summary)
- [ ] IDE-compatibility fields set if needed (copilot_compatible, disable-model-invocation)
- [ ] Registered in .ai-engineering/manifest.yml (skills.registry or agents.names + total)
- [ ] Mirror sync run: python scripts/sync_command_mirrors.py
- [ ] Tests pass: source .venv/bin/activate && python -m pytest tests/unit/ -q
- [ ] Pain sources consulted (decision-store, LESSONS.md) for constraints

---

Workflow

Two modes:

• skill <name> — context load (overlap check + pain sources), delegate to skill-creator for TDD + evals, register in manifest.yml, sync mirrors.
• agent <name> — scaffold the agent file, declare frontmatter (description, model, tools, dispatch source), register in manifest.yml, sync mirrors.

Mode: skill <name>

Phase 1 — ai-engineering Context (this skill owns this)

Follow handlers/create-skill.md. Before creating anything, load project context:

1. Check for overlap — read .ai-engineering/manifest.yml skill registry. If a skill already covers this capability, evolve it with /ai-skill-improve instead.
2. Load pain sources — read decision-store.json, LESSONS.md, observations.yml for constraints (e.g., DEC-003 plan/execute split, similar-skill failures, instinct sequences this skill should optimize).
3. Determine IDE compatibility — see IDE-Compatibility Frontmatter below.

Phase 2 — Delegate to skill-creator for TDD + Evals

Invoke Anthropic's skill-creator with this context:

Create a new skill called "ai-{name}" for the ai-engineering framework.

Context about the framework:
- Skills live in .github/skills/ai-{name}/SKILL.md
- They follow this frontmatter format: name, description (CSO-optimized), effort, argument-hint, tags
- The description field is the primary triggering mechanism — it must describe WHEN to use, not WHAT it does
- Pain sources found: [pass relevant lessons, decisions, instinct patterns from Phase 1]

The skill should:
[pass the user's requirements]

Look at existing skills like .github/skills/ai-security/SKILL.md or .github/skills/ai-review/SKILL.md
for format reference.

skill-creator owns drafting, TDD pressure testing, eval pipeline (grader/analyzer/benchmark/HTML viewer), description-optimization, and iteration. After it returns, verify the SKILL.md follows ai-engineering conventions (Step 0 context loading, output contract), frontmatter has all required fields, and description is CSO-optimized.

Phase 3 — Register and Sync (this skill owns this)

Walk the Registration Checklist (Start Here) and handlers/validate.md. Manifest entry shape: ai-{name}: { type: <type>, tags: [<tags>] }; bump skills.total. Mirror sync: python scripts/sync_command_mirrors.py. Tests: source .venv/bin/activate && python -m pytest tests/unit/ -q. Update README.md skill counts if they changed.

---

Mode: agent <name>

Follow handlers/create-agent.md. Agents don't go through skill-creator (they're not skills) — create them directly:

1. Define mandate — singular responsibility (one thing).
2. Load pain sources — same as skill Phase 1; check decision-store for agent-architecture constraints (e.g., DEC-019).
3. Scaffold .github/agents/{name}.agent.md with: Identity (role/experience/specialization), Mandate (owns/does-not-own), Capabilities (declared permissions: read-only/read-write/paths), Behavior (modes/procedures), Output Contract (structured format), Boundaries (hard limits/escalation), Self-challenge protocol (pre-action questions).
4. Register in manifest.yml agents section (names array + total count).
5. Create matching skill — if /ai-{name} entry point is needed, scaffold via /ai-scaffold skill {name}.
6. Sync and test — same as skill Phase 3.

---

CSO Description Patterns

The description field is the skill's search ranking — it determines whether the skill triggers. It must describe triggering conditions, not summarize functionality.

Bad (summary)	Good (CSO trigger)
"Generates standup notes"	"Use when preparing daily standup notes or summarizing recent PR activity"
"Sprint planning tool"	"Use when planning a new sprint or running a retrospective"
"Resolves git conflicts"	"Use when git reports merge conflicts during rebase, merge, or cherry-pick"

IDE-Compatibility Frontmatter

Field	Effect
copilot_compatible: false	Excludes from .github/skills/ mirror (Claude Code-only skills)
codex_compatible: false	Excludes from .codex/skills/ mirror
disable-model-invocation: true	Tells GitHub Copilot not to invoke LLM (script-only skills)

ai-analyze-permissions is the current example of a provider-scoped skill: it opts out of GitHub Copilot and Codex mirrors.

Quick Reference

/ai-scaffold skill standup     # create a new standup skill (delegates TDD to skill-creator)
/ai-scaffold agent reviewer    # create a new reviewer agent (direct scaffold)

Examples

Example 1 — create a brand-new skill

User: "the framework needs a capability for OpenAPI schema validation — create the skill"

/ai-scaffold skill ai-openapi

Loads pain context, delegates draft + TDD to skill-creator, registers in manifest.yml, runs sync_command_mirrors.py, verifies tests still pass.

Example 2 — scaffold a new specialist agent

User: "add a new reviewer agent for accessibility"

/ai-scaffold agent reviewer-accessibility

Scaffolds the agent file with CSO description, tools whitelist, model: sonnet, dispatch-source comment; registers in manifest; syncs mirrors.

Integration

Delegates to: Anthropic skill-creator (TDD + evals + description optimization). Reads: manifest.yml, decision-store.json, LESSONS.md. Calls: python scripts/sync_command_mirrors.py. See also: /ai-skill-improve (improve existing), /ai-prompt-tune (description-only).

$ARGUMENTS