| name | create-skill |
| description | Scaffold and ship a new SKILL.md through the full creation lifecycle — design, implement, structural audit, trigger eval, and evidence recording. Use when creating a skill from scratch or formalizing an existing one, even if the user just says "I want a skill for X" or "help me build this."
|
Create Skill
Gotchas
- Never use
@latest: Resolve the pinned version first: npm view cyberplace version, then use npx cyberplace@0.2.3.
Lifecycle
Research → Design → Implement → Audit → Test → Evidence → Ship
Each phase gates the next. Do not skip ahead.
Phase 1 — Research
Before writing anything, check what is already known:
- Search
.research/ for findings relevant to the skill's domain.
- If the skill enforces non-obvious criteria (thresholds, patterns, rankings), identify the authoritative source now. You will record it in Phase 6.
- If no prior research applies, proceed — you will record new evidence in Phase 6 after testing confirms the criteria work.
Phase 2 — Design
Answer all five questions before writing a line of SKILL.md:
| Question | What to decide |
|---|
| Scope | What exactly does this skill do? One workflow only. |
| Trigger condition | When should it fire? List both explicit and implicit phrasings. |
| Output contract | What artifact does it produce? File path, report format, or decision? |
| Quality bar | How will you know a run succeeded? Define a concrete pass condition. |
| Out of scope | What must this skill explicitly NOT do? |
If you cannot answer all five, stop and resolve them with the user before proceeding.
Phase 3 — Implement
- Create
skills/<name>/SKILL.md (user-level: ~/.agents/skills/<name>/SKILL.md).
- Write frontmatter:
name: kebab-case, must match the directory name exactlydescription: capabilities + "Use when…" trigger condition + implicit phrasing examples. Target 150–400 characters. See .research/skill-description-guidelines/conclusion.md.
- Write body: step-by-step instructions, gotchas, output format. Keep under 500 lines.
- Add
references/ only for material that is large, rarely needed, and has explicit load conditions in the body.
- Create
evals/ — at minimum evals/trigger-queries.json with labeled should/should-not-trigger queries. See test-skill for the file formats.
Phase 4 — Structural audit
Run the aced improve-skill skill on the new skill before any testing — it bundles the mechanical
validate.mts engine that runs the structural checks without an LLM:
node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<name>
- Resolve all CRITICAL and HIGH findings before proceeding.
- MEDIUM findings must be resolved or explicitly deferred with a documented reason in the commit message.
Phase 5 — Test
Run test-skill to validate trigger accuracy and output quality:
Use the test-skill skill on skills/<name>
Pass criteria:
- Trigger accuracy: ≥80% of should-trigger queries activate the skill; ≥90% of should-not-trigger queries do not.
- Output quality: all scenario evals pass their expected output check.
If trigger accuracy is below threshold, revise the description and re-run. See .research/skill-description-guidelines/conclusion.md for the optimization approach.
Do not proceed to Phase 6 until both pass.
Phase 6 — Evidence
If the skill enforces non-obvious criteria, record the evidence:
.research/<criteria-slug>/
├── conclusion.md # current best answer (read this first)
├── topic.md # full investigation record
├── evidence.md # claims with confidence levels and source URLs
└── changes.md # dated update history
Link from the relevant check definition back to the research slug.
Skip only if: (a) all criteria are direct spec requirements with a cited URL already in the check definition, or (b) every criterion is already covered by an existing .research/ slug that is still current.
Phase 7 — Ship
- Run
improve-skill one final time — all checks must pass.
- Commit:
feat(skills): add <name> skill.
- If publishing to a registry, run
publish-universal-plugin.
