create-skill

name	create-skill
description	Use when creating a new charness skill or improving a migrated one. Defines the canonical portable authoring contract: classify public/support/profile/integration boundaries, simulate failure modes, keep host-specific behavior in adapters and presets, and express external tool dependencies through manifests instead of hidden assumptions.

Create Skill

Use this when the task is to create, migrate, split, or normalize a skill in charness.

Bootstrap

Resolve $SKILL_DIR per ../../shared/references/bootstrap-resolution.md. Every invocation starts here. Read only the files that affect the current change.

# Required Tools: rg
# 1. charness boundary and current product context
sed -n '1,220p' README.md
sed -n '1,220p' docs/handoff.md 2>/dev/null || true
python3 "$SKILL_DIR/scripts/resolve_adapter.py" --repo-root .

# 2. existing target or source skill
rg --files skills/public skills/support
sed -n '1,240p' "$SKILL_DIR/../<skill-id>/SKILL.md"
sed -n '1,240p' "$SKILL_DIR/../../support/<skill-id>/SKILL.md"

# 3. external-tool or profile context when relevant
sed -n '1,240p' docs/control-plane.md
sed -n '1,260p' docs/public-skill-validation.md 2>/dev/null || true
sed -n '1,220p' docs/public-skill-dogfood.md 2>/dev/null || true
sed -n '1,260p' integrations/tools/manifest.schema.json
sed -n '1,260p' skills/support/capability.schema.json
sed -n '1,240p' profiles/profile.schema.json
sed -n '1,220p' presets/README.md

Read the resolver JSON before continuing. Stop and repair the adapter when valid is false; when found is false, name the visible generic topology fallback in the brief before using inferred vocabulary. Run python3 "$SKILL_DIR/scripts/init_adapter.py" --repo-root . to scaffold the canonical adapter when the repo should own topology terms.

Workflow

1. Classify the artifact before editing.
   • public skill: one user-facing concept
   • support skill: teaches tool usage without becoming product philosophy
   • profile: default bundle of public and support skills
   • preset: opt-in default values for adapters or hosts
   • integration: external ownership contract, never a hidden dependency
2. Write a capability brief before changing files.
   • concept, audience, trigger, and consumer capability or capability failure
   • current and next center only when improving an existing skill or when order matters
   • external dependencies, adjacent-skill behavior rules, accumulated state, proof boundary
   • implementation topology: shared implementation, repo-local placements, aliases, or intentional fork signals from the adapter
   • cold start, warm start, error recovery, and concrete failure cases
   • source/principal binding drift or prescribed-path self-test concerns when relevant
3. Freeze the current consumer contract before editing an existing public skill.
   • read the current reviewed dogfood case or scaffold it first with python3 "$SKILL_DIR/../quality/scripts/suggest_public_skill_dogfood.py" --repo-root . --skill-id <skill-id> --detail
   • decide whether the slice claims preserve or improve; if improve, name the capability failure before changing the core trigger or behavior contract
   • when the change touches adapters, examples, bootstrap, first-touch docs, or repo-local skill customization, run a customer-of-this-skill critique before editing: name the user or downstream agent, the first prompt they will try, and the adapter states that could make the first run fail
   • run success criteria review for public-skill behavior changes; use it inline for narrow edits and as a bounded subagent review for non-trivial first successful trigger, default, artifact, or proof-path changes
   • if the skill is evaluator-required, inspect scenario coverage and proof planning before editing
   • when the checked-in contract is too vague to freeze, tighten the scenario first
4. Decide the portability seams.
   • skill body stays generic
   • repo or host specifics move to adapter files or presets
   • when one skill spans multiple repo-local placements, use the adapter's topology vocabulary to decide shared implementation versus intentional fork before writing files
   • optional fields must distinguish unset from explicitly empty
   • prefer strong defaults and inference over user-facing branches or flags
5. Decide dependency ownership honestly.
   • harness-owned support logic belongs in skills/support/
   • if charness owns the runtime capability, keep its machine-readable metadata next to the support skill as skills/support/<skill-id>/capability.json
   • external tools and upstream support skills belong in <repo-root>/integrations/tools/<tool-id>.json
   • if an upstream support skill already exists, prefer reference, sync, or a thin wrapper over copying
   • keep manifest metadata rich enough to reveal capability kind and supported access modes
   • express setup prerequisites as manifest readiness checks
   • use create-cli for repo-owned command lifecycle; use deployable packaging refs for plugin bundle proof
   • when the skill depends on an external or runtime capability, name which proof levels apply per ../../shared/references/external-capability-proof-ladder.md (surface, worker_queued, host_decision, provider_roundtrip, agent_choice) and which the host must satisfy
6. Implement the smallest coherent package.
   • SKILL.md contains trigger contract and decision skeleton only
   • treat sparse named person anchors in SKILL.md core as a deliberate retrieval tool when they materially improve recall of a real reasoning frame
   • keep the behavior or capability rule in core when it should shape repeated moves; put factual essence, nuance, and reference contents in references/
   • for sequencing-shaped skill improvements, consume ../../shared/references/generative-sequence.md lightly instead of embedding that lens in this skill
   • move schemas, examples, prose theory to references/; keep tokens a closeout emits VERBATIM in a core ## Closeout Vocabulary H2 (that ref's rule)
   • add scripts for repeated bootstrap, adapter resolution, artifact upsert, or recovery behavior that would otherwise become prose-only ritual
   • ship a deterministic planner emitting the canonical run-plan envelope (../../shared/references/run-plan-envelope.md) ONLY when the skill has a real briefing decision; linear ones use its minimal emitter (no fake branches), and a skill with no briefing decision ships none — forcing one is concept-adding boilerplate
7. Verify before stopping.
   • cold-start test from repo root
   • for public-skill changes, run one realistic consumer prompt instead of stopping at producer-side validators; include missing, stale, and thin adapter states when adapters or repo-local defaults shape the first run
   • use python3 "$SKILL_DIR/../quality/scripts/suggest_public_skill_dogfood.py" --repo-root . --skill-id <skill-id> to scaffold prompt, repo shape, expected artifact, and acceptance evidence
   • decide whether dogfood, evaluator scenarios, or scenario-review artifacts move in the same slice
   • trigger collision check against adjacent skills
   • path check for every file named in the skill
   • schema or example validation for any profile, preset, or manifest touched
   • when the skill's Output Shape declares classifier fields the caller must act on, apply the references/portable-authoring.md "Closeout Schema Rule" — ship a section-gated validator; that rule names the advisory survey that lists skills still carrying a classifier-bearing Output Shape without one

Rules

• Maximize reuse first. Port an existing skill body or reference when it already captures the right behavior.
• Do not let a public skill smuggle multiple concepts; a body at the length cap is that smell — separate a concept into its own skill or delete it, never shave lines or displace overflow into references/ (north-star P2).
• Use a named person anchor in the public core only when it reliably retrieves a real reasoning frame (the decoration/strip guidance and the multi-skill propagation rule live in references/portable-authoring.md "Named Anchor Rule").
• Keep selection logic in SKILL.md core. References should deepen a chosen move, not become a second workflow that re-decides when to act.
• Keep host-specific behavior and repo-local placement topology out of the SKILL.md body; use create-skill adapter terms/presets for implementation identity, exposed placements, aliases, and intentional fork signals.
• Keep expert references source-faithful and minimal. Verify fuzzy or non-obvious claims before compressing them into a public skill or reference.
• Prefer strong defaults over user-facing branches or flags; add a branch only when the behaviors are genuinely distinct, user-meaningful, and unsafe to infer (references/portable-authoring.md "Option Minimalism").
• External tool dependencies must be explicit in manifests and degradation rules, not implied by a casual command example.
• When a host may be isolated, prefer grant-first and authenticated-binary flows over direct secret-file assumptions.
• Presets are explicit defaults, not hidden behavior changes.
• Use WebSearch explicitly for research steps; do not imply it weakly.
• Never ask users to paste secrets into chat.
• If a skill needs the same bootstrap, adapter resolution, artifact upsert, or recovery step more than once, ship a helper script instead of leaving the behavior as prose-only ritual.
• Treat public-skill frontmatter and generated AGENTS hints as classifier input, not only documentation; prove at least one realistic consumer prompt for the changed skill before calling the slice done.
• Do not rewrite an existing public-skill core until you have decided how the current intent is frozen: reviewed dogfood, cautilus scenario coverage, or a checked-in scenario review artifact.
• Do not treat a package-valid public skill as customer-valid. For adapter, bootstrap, example, or first-touch doc changes, prove the changed skill from the customer repo's first prompt before trusting producer-side checks.
• Do not treat an author's free-form smoke test as proof; the passing path must be reproducible from the installed or checked SKILL.md alone.
• For evaluator-required skills, treat maintained scenario coverage and cautilus proof planning as part of the edit contract.
• When adding a high-leverage reasoning or review pattern to one public skill, inspect adjacent public skills for obvious propagation opportunities before stopping.
• If the adjacent skill sits at its line ceiling (surface preflight warns near-cap), split a concept out of it into its own surface or delete one — never trim prose to make the line fit, and never silently drop the reciprocal line.

References

• references/adapter-contract.md
• references/portable-authoring.md
• references/adapter-pattern.md
• references/preset-conventions.md
• references/integration-seams.md
• references/runtime-capabilities.md
• references/deployable-skill-packaging.md
• references/binary-preflight.md
• ../create-cli/SKILL.md
• ../../shared/references/binary-preflight.md
• ../../shared/references/run-plan-envelope.md
• ../../shared/references/source-bound-records.md
• ../../shared/references/prescribed-path-self-test.md
• ../../shared/references/success-criteria-review.md
• ../../shared/references/external-capability-proof-ladder.md