Define Skill

Define Skill

Create or improve a workflow skill — a process, tool-based, or standard SKILL.md — then hand it to the ACED eval loop to spec and score.

When the conductor dispatches this skill as a generic builder (produced-by sdd:automaton) for the ACED impl-producer role (implement mode, against a frozen .feature), it builds the SKILL.md to pass the frozen suite. The verification is the frozen .feature itself — its inline @rubric scenarios and @trigger Examples, authored by aced-scenario-writer at explore — so no separate eval suite is authored here; eval.md carries only the subject binding and run policy. As impl-producer it self-aligns to sdd:ownership-governance plus the resolved builder-impl + architect-impl bars (the ACED builder-impl is aced:aced-builder-impl). If the impl-judge reports scenario failures, load aced-impl-producer to run the diagnose-and-refine loop rather than re-deriving it here.

There are two other entry points, both with no frozen .feature and only the SKILL.md produced:

• Standalone — the user invokes this skill directly, outside any CR. Scaffold, then offer the ACED eval loop (see "Report and hand off" below) rather than assuming it.
• Escaped — the gateway or start-mission invokes this skill directly after resolving the request non-durable (the escape hatch, before any CR opens). There is no mission to hand off within: scaffold, audit, report, and stop — do not mention the ACED eval loop.

Route the request first

define-skill owns workflow skills. Defer when the intent belongs to a sibling that carries the same config vocabulary:

A persona request that surfaces mid-authoring is handed to define-agent — do not scaffold a persona skill here.

Load the governance

Before writing content, load the skill-design governance and read stdout as the authoritative rules for principles, progressive disclosure, description structure, and when to extract deterministic logic to a script:

npx cyberplace@0.2.2 governance show skill-design   # resolve <version> via: npm view cyberplace version — never @latest

If the skill will ship a scripts/ directory or document CLI commands agents run, also load agent-tool-output for stdout / JSON / non-interactive / stderr rules.

Settle the shape — five questions

Answer all five before writing a line of SKILL.md. If any cannot be inferred from what the user has said, ask the user to resolve it — never invent it:

Choose the pattern

Capture the workflow shape (separate from placement). A persona is not a pattern here — route it to define-agent.

Resolve placement and runtimes

Pick placement before scaffolding; if unclear from context, ask:

Check whether npx skills is available, then scaffold at the derived path:

npx skills --version 2>/dev/null && npx skills init <name> --dir <placement-dir>   # else: mkdir -p <placement-dir>/<name>

Ask which runtimes to target; the SKILL.md is the canonical file, each runtime location is a symlink to it. Create and verify one symlink per selected runtime:

ln -sf <relative-path-to-canonical> <runtime-location> && ls <runtime-location>   # verify it resolves

Draft the SKILL.md

Write the file at the canonical path:

---
name: <name>          # kebab-case, must match the directory name exactly
description: <capability> + "Use when <trigger>" + an implicit-phrasing example ("even if they say …")
---

# <Title>

## When to use
<the trigger condition, restated for the body>

## Instructions
1. <step>
2. <step>

• Description — the only field loaded at startup; it carries the whole triggering burden. Target 150–400 characters (≤1024 hard limit): capability + "Use when…" + an implicit phrasing. For a partial skill (a reusable part other skills call by name, not user-triggered), set user-invocable: false and lead the description with the "Partial Skill:" prefix (recommended form "Partial Skill: invoke by name only — <identity>. <caller>."), kept minimal and non-trigger-shaped so it does not self-activate.
• Body — step-by-step, under 500 lines. Keep the when here; move any deterministic, fixed-output step to a scripts/ file or an existing CLI and have the body only say when to run it.
• Project-public skills get a README.md beside the SKILL.md (title, when-to-use, what-it-does, install line). User-global skills get none.

Improving an existing skill

If the target SKILL.md already exists, read it first and change only the gaps or issues found — leave every sound part intact. This fills gaps in a skill's definition; diagnosing failing evals is improve.

Name gate/case scorers by role

For a subagent this skill scaffolds (realized as a partial skill, e.g. loaded via the ACED impl-producer/impl-judge pattern): if its role is to score or verify a specific gate or case, name it by that gate/scope, not a bare action verb — <domain>-<gate>-judge for a gate scorer (e.g. aced-impl-judge), <domain>-case-judge for a case scorer (e.g. aces-case-judge). Reject implementer, judge, validator, reviewer, checker alone. A producer subagent (e.g. scenario-writer, doc-writer) keeps its action-oriented name — this check does not fire for it.

Evaluate this in-skill quality check — separate from the mechanical audit validate below — before handing the skill back: a drafted gate/case scorer named with a bare action verb is a HIGH severity finding; fix it (rename to the gate-and-scope form) before presenting the skill.

Audit before handing back

Run the structural audit and fix any CRITICAL or HIGH finding before presenting the skill:

npx cyberplace@0.2.2 audit validate --path <placement-dir>/<name>

For a fuller pass, invoke the improve-skill skill. Do not present a skill with an open CRITICAL finding.

Report and hand off to the ACED eval loop

Summarize:

• Canonical SKILL.md path
• README path (project-public only)
• Runtime symlinks created and verified
• Audit outcome

Escaped entry: stop here — the artifact resolved non-durable, so there is no mission to hand off to.

Standalone or impl-producer entry: point the user at the ACED eval loop to spec and score the skill — run sdd:start-mission (the conductor resolves the ACED roles for the skill artifact-type) to author its frozen .feature (with inline @rubric), or add-scenario / run to grow and score it. Do not embed a legacy trigger-query eval file as the test step — scoring is the ACED loop's job.