| name | skill-development |
| description | Design, create, revise, evaluate, instrument, secure, and release reusable agent skills from observed successful workflows or recurring reviewed failures. Use when deciding whether behavior belongs in a skill, retrieval source, script, tool, hook, prompt, or repository instruction; creating or updating a skill package; defining triggers and progressive disclosure; setting up skill telemetry and tracing; selecting model and reasoning-effort lanes; comparing a candidate with no-skill or built-in skill creators; promoting reviewed traces into regression cases; or making an evidence-backed release decision. Do not use for one-off task instructions, speculative workflows with no inspected examples, or merely installing an existing skill. |
Develop an Evidence-Backed Skill
Build the smallest reusable control that demonstrates benefit on the tasks and
harnesses where it will run. Treat loadability as a structural check, not proof
that the skill helps.
Read corpus-evidence.md before making a
material design, telemetry, model-route, or release recommendation. Treat the
packaged evidence boundary as the local source of truth; follow its public
source links only when a time-sensitive product fact needs verification.
Establish the Case
- Name the demonstrated successful workflow or recurring reviewed failure.
- Record its source, frequency or severity, workaround, owner, and observable
accepted outcome using
assets/templates/proposal.json.
- Reject a speculative skill when no inspected evidence shows a reusable job.
Gather examples or improve the interface first.
- Read evidence-and-containers.md to
decide whether the control belongs in a skill, retrieval, executable
mechanism, hook, repository instruction, or one task's prompt.
Define One Operational Contract
Write one job, discriminative positive and negative triggers, explicit inputs
and outputs, a safe default, forbidden effects, and observable completion
checks. Keep consequential ambiguity with the strongest responsible agent or a
human owner.
Read design-and-disclosure.md before
adding resources. Keep discovery metadata precise, SKILL.md operational, and
branch-specific references, scripts, and assets one direct link away. Apply the
deletion test to duplication, generic knowledge, sediment, sprawl, and
instructions that do not change observed behavior.
Build the Package
Use the current harness's official initializer when one is available. Then run:
python3 scripts/scaffold_package.py <skill-directory> --proposal proposal.json
Resolve scripts/scaffold_package.py relative to this SKILL.md, not the task
working directory. Create the proposal from the adjacent
assets/templates/proposal.json schema and keep the scaffold's canonical
filenames; automation depends on them. Do not substitute prose reports such as
RELEASE.md or telemetry-policy.md for the machine-readable JSON contracts.
The scaffold adds the proposal, owned evaluation skeleton, privacy-first
telemetry policy, release record, and result-status file without overwriting
existing artifacts. Replace its example cases and route placeholders with the
real contract before evaluation.
Keep deterministic mechanics in scripts so agents execute them without loading
their implementation. Keep the portable behavioral core vendor-neutral; put
Codex, Claude, and Pi invocation or exact model configuration in agents/ or
evals/routes.json, not portable frontmatter.
Select Model, Effort, and Execution Topology
Read routing-and-latency.md. Express the
skill's minimum lane as efficient, balanced, or frontier and place current
model IDs in the route manifest. Change one routing variable at a time while
holding the task, tools, permissions, environment, timeout, and verifier fixed.
Use a capable quality-ceiling run before optimizing ambiguous or consequential
work. Start bounded deterministic work on an efficient lane and escalate only
when the verifier exposes a capability gap. Delegate only independent bounded
work with an explicit return contract.
Instrument Before Release
Read telemetry-and-tracing.md. Start with
metadata-only task traces. Record offered, selected, activated, expanded,
executed, and evaluated skill lifecycle events plus exact package, harness,
model, prompt, tool, case, and evaluator versions. Keep content capture off by
default and separate operational traces from immutable evaluation cases.
Do not infer quality from activation count. Join each valid run to an accepted,
failed, invalid, or delayed outcome and report tokens, cost, latency, retries,
tool and permission waits, and human rework per accepted task.
Audit Before Executing or Releasing
Inventory every bundled file, dependency, permission, external fetch, and
third-party source. Run:
python3 scripts/audit_package.py <skill-directory>
python3 scripts/package_hash.py <skill-directory>
Inspect every finding; a green structural audit does not establish behavioral
quality or third-party trust. Read
security-and-provenance.md for the
release audit.
Evaluate Against Real Controls
Read evaluation-and-release.md. Keep
cases, routing prompts, development and held-out splits, route manifests,
runner, comparator, raw results, release decision, and limitations inside the
skill's own evals/ directory.
Evaluate separately:
- automatic routing;
- forced conditional efficacy; and
- automatic end-to-end utility.
Compare no-skill, the current incumbent or built-in creator, and the candidate
within each harness using fresh sessions and clean workspaces. Use three
development repetitions and five held-out release repetitions. Preserve every
valid run; classify harness, environment, telemetry, evaluator, and task
failures separately.
Do not launch nested model-backed evaluation merely because a new package is
being scaffolded. When execution is outside the user's request, authorization,
or declared budget, create the runnable comparison, leave the release decision
at defer, and state exactly which runs remain. Structural and unit checks are
still required before handoff.
Start at alpha with explicit invocation. Promote only through the predeclared
quality-first gate. Freeze every release candidate; any behavioral change makes
a new candidate and requires held-out replay. State "unverified" outside the
tested task, model, effort, harness, and tool matrix.
Finish
Finish only when the contract is clear, deterministic checks pass, source and
security review is complete, the candidate has credible paired evidence over
its controls, telemetry and evaluation artifacts are retained, and the owner
records a release decision with limitations. Do not claim general superiority
from one smoke run or from structural checks alone.
