Create Skill

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:

1. Search .research/ for findings relevant to the skill's domain.
2. If the skill enforces non-obvious criteria (thresholds, patterns, rankings), identify the authoritative source now. You will record it in Phase 6.
3. 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:

If you cannot answer all five, stop and resolve them with the user before proceeding.

Phase 3 — Implement

1. Create skills/<name>/SKILL.md (user-level: ~/.agents/skills/<name>/SKILL.md).
2. Write frontmatter:
   • name: kebab-case, must match the directory name exactly
   • description: capabilities + "Use when…" trigger condition + implicit phrasing examples. Target 150–400 characters. See .research/skill-description-guidelines/conclusion.md.
3. Write body: step-by-step instructions, gotchas, output format. Keep under 500 lines.
4. Add references/ only for material that is large, rarely needed, and has explicit load conditions in the body.
5. 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

1. Run improve-skill one final time — all checks must pass.
2. Commit: feat(skills): add <name> skill.
3. If publishing to a registry, run publish-universal-plugin.