Skill Creator
Intent
- Goal: Create or change one reusable skill with a single body, complete frontmatter, and an IDSD body.
- Limits:
- Do not create a skill when documentation already exists (create a reference instead), the pattern is trivial or self-explanatory, or the task is one-off.
- Never copy skill bodies; never keep an exclusive skill at the top level.
- No Keywords section (agents search frontmatter), no troubleshooting sections, no lengthy explanations or duplicated docs (reference instead), no web URLs in references (use local paths).
- Fails if: the skill already exists (check
domains/*/skills/*/SKILL.md and skills/*/SKILL.md); frontmatter name differs from the directory basename or is not oc-<short-name>; metadata.version is not strict SemVer or metadata.status misstates lifecycle; a multi-domain skill lacks a symlink from every owner; no manual coverage key was updated and no new immutable manual case was added.
Context
- Reads: existing skills,
CONTRIBUTING.md (## IDSD format, ## Skills), and references/behavioral-evaluation.md when applicable.
- Never reads: none.
- Persona: concise skill author.
- Scope: the user asks to create or change a skill, add agent instructions, or document patterns for AI; create one only when a pattern is used repeatedly and AI needs guidance; project conventions differ from generic best practices; complex workflows need step-by-step guidance; decision trees help AI choose the right approach.
Expectations
- Scenarios:
- WHEN one domain uses the skill THEN its body is
domains/{domain}/skills/{skill-name}/.
- WHEN multiple domains use it THEN one body lives at
skills/{skill-name}/ and every owner links domains/<domain>/skills/<skill-name> -> ../../../skills/<skill-name>.
- WHEN a high-impact discipline skill shows a reproducible agent failure despite being available THEN run the bounded pilot in references/behavioral-evaluation.md: pre-written criteria, a no-guidance control, multiple fresh-context runs per arm, preserved raw receipts, manual scoring, reported variance and cost. Never a routine step or CI gate;
python3 scripts/lint-manual-tests.py validates catalog metadata, links, and coverage, not model behavior.
- Done means: the skill exists at the right location with complete frontmatter (description includes trigger keywords), an IDSD body with every ICE field, accurate version and status, and updated manual coverage.
- Quality needs: most critical rules first; tables for decision trees; minimal, focused examples; a commands block only when repeatable commands are part of the contract.
Method
Structure
{skill-root}/{skill-name}/ # skill-root: domains/{domain}/skills or skills
├── SKILL.md # Required
├── assets/ # Optional: generated templates, schemas, fixtures, examples
└── references/ # Optional: longer guidance, edge cases, explanatory docs
Concrete generated material goes in assets/; explanatory material goes in references/.
SKILL.md template
---
name: oc-{short-name}
description: >
{One-line description of what this skill does}.
Trigger: {When the AI should load this skill}.
license: Apache-2.0
metadata:
author: {author}
version: "1.0.0"
status: backlog
---
# {Title}
## Intent
- **Goal:** {one observable outcome}
- **Limits:** {boundaries, forbidden actions}
- **Fails if:** {observable failure conditions}
## Context
- **Reads:** {inputs and evidence}
- **Never reads:** {excluded sources}
- **Persona:** {role and stance}
- **Scope:** {activation and where it applies}
## Expectations
- **Scenarios:** {WHEN ... THEN ...}
- **Done means:** {completion criteria and return contract}
- **Quality needs:** {quality bar}
## Method
{Optional: decision tables, formats, commands, and resource pointers such as [assets/](assets/) and [references/](references/).}
Frontmatter
| Field |
Required |
Description |
name |
Yes |
oc-<short-name>: kebab-case, at most three short words after the prefix |
description |
Yes |
What + Trigger in one block |
license |
Yes |
Commonly MIT or Apache-2.0 |
metadata.author |
Yes |
Skill author or maintainer |
metadata.version |
Yes |
Semantic version as string |
metadata.status |
Yes |
backlog, in-progress, testing, or done |
Version bumps: patch for wording/path/template/internal contract fixes, minor for new capabilities or optional flows, major for breaking activation/output behavior.
1---2name: oc-skill-creator3description: >4 Creates new AI agent skills following the Agent Skills spec.5 Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI.6license: Apache-2.07metadata:8 author: gentleman-programming9 adapted_by: andresnator10 source: https://skillmd.com/skills/andresnator/oc-skill-creator11 upstream: gentleman-programming/sdd-agent-team12 version: "3.1.0"13 status: in-progress14---1516# Skill Creator1718## Intent1920- **Goal:** Create or change one reusable skill with a single body, complete frontmatter, and an IDSD body.21- **Limits:**22 - Do not create a skill when documentation already exists (create a reference instead), the pattern is trivial or self-explanatory, or the task is one-off.23 - Never copy skill bodies; never keep an exclusive skill at the top level.24 - No Keywords section (agents search frontmatter), no troubleshooting sections, no lengthy explanations or duplicated docs (reference instead), no web URLs in references (use local paths).25- **Fails if:** the skill already exists (check `domains/*/skills/*/SKILL.md` and `skills/*/SKILL.md`); frontmatter `name` differs from the directory basename or is not `oc-<short-name>`; `metadata.version` is not strict SemVer or `metadata.status` misstates lifecycle; a multi-domain skill lacks a symlink from every owner; no manual coverage key was updated and no new immutable manual case was added.2627## Context2829- **Reads:** existing skills, `CONTRIBUTING.md` (`## IDSD format`, `## Skills`), and `references/behavioral-evaluation.md` when applicable.30- **Never reads:** none.31- **Persona:** concise skill author.32- **Scope:** the user asks to create or change a skill, add agent instructions, or document patterns for AI; create one only when a pattern is used repeatedly and AI needs guidance; project conventions differ from generic best practices; complex workflows need step-by-step guidance; decision trees help AI choose the right approach.3334## Expectations3536- **Scenarios:**37 - WHEN one domain uses the skill THEN its body is `domains/{domain}/skills/{skill-name}/`.38 - WHEN multiple domains use it THEN one body lives at `skills/{skill-name}/` and every owner links `domains/<domain>/skills/<skill-name> -> ../../../skills/<skill-name>`.39 - WHEN a high-impact discipline skill shows a reproducible agent failure despite being available THEN run the bounded pilot in [references/behavioral-evaluation.md](references/behavioral-evaluation.md): pre-written criteria, a no-guidance control, multiple fresh-context runs per arm, preserved raw receipts, manual scoring, reported variance and cost. Never a routine step or CI gate; `python3 scripts/lint-manual-tests.py` validates catalog metadata, links, and coverage, not model behavior.40- **Done means:** the skill exists at the right location with complete frontmatter (description includes trigger keywords), an IDSD body with every ICE field, accurate version and status, and updated manual coverage.41- **Quality needs:** most critical rules first; tables for decision trees; minimal, focused examples; a commands block only when repeatable commands are part of the contract.4243## Method4445### Structure4647```48{skill-root}/{skill-name}/ # skill-root: domains/{domain}/skills or skills49├── SKILL.md # Required50├── assets/ # Optional: generated templates, schemas, fixtures, examples51└── references/ # Optional: longer guidance, edge cases, explanatory docs52```5354Concrete generated material goes in `assets/`; explanatory material goes in `references/`.5556### SKILL.md template5758```markdown59---60name: oc-{short-name}61description: >62 {One-line description of what this skill does}.63 Trigger: {When the AI should load this skill}.64license: Apache-2.065metadata:66 author: {author}67 version: "1.0.0"68 status: backlog69---7071# {Title}7273## Intent7475- **Goal:** {one observable outcome}76- **Limits:** {boundaries, forbidden actions}77- **Fails if:** {observable failure conditions}7879## Context8081- **Reads:** {inputs and evidence}82- **Never reads:** {excluded sources}83- **Persona:** {role and stance}84- **Scope:** {activation and where it applies}8586## Expectations8788- **Scenarios:** {WHEN ... THEN ...}89- **Done means:** {completion criteria and return contract}90- **Quality needs:** {quality bar}9192## Method9394{Optional: decision tables, formats, commands, and resource pointers such as [assets/](assets/) and [references/](references/).}95```9697### Frontmatter9899| Field | Required | Description |100|-------|----------|-------------|101| `name` | Yes | `oc-<short-name>`: kebab-case, at most three short words after the prefix |102| `description` | Yes | What + Trigger in one block |103| `license` | Yes | Commonly `MIT` or `Apache-2.0` |104| `metadata.author` | Yes | Skill author or maintainer |105| `metadata.version` | Yes | Semantic version as string |106| `metadata.status` | Yes | `backlog`, `in-progress`, `testing`, or `done` |107108Version bumps: patch for wording/path/template/internal contract fixes, minor for new capabilities or optional flows, major for breaking activation/output behavior.