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

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

# 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

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 short brief before changing files.
   • concept, audience, trigger, external dependencies, accumulated state
   • candidate anchors and adjacent-skill behavior rules
   • cold start, warm start, error recovery, and concrete failure modes
   • 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> --json
   • decide whether the slice claims preserve or improve 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
   • 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 rule in core when the philosophy should shape repeated moves; put factual essence, nuance, and reference contents in references/
   • move schemas, examples, and theory into references/
   • add scripts for repeated bootstrap, adapter resolution, artifact upsert, or recovery behavior that would otherwise become prose-only ritual
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

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 just because the old repo had several narrow expert surfaces.
• Use a named person anchor in the public core when it reliably retrieves a real reasoning frame; do not use names as decoration or strip them out when the public trigger actually benefits from the anchor.
• When one philosophy should shape several adjacent skills, encode its behavioral translation in each core and keep only the anchors that materially improve retrieval.
• 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 expert references source-faithful and minimal. Verify fuzzy or non-obvious claims before compressing them into a public skill or reference.
• Host-specific behavior belongs in adapters and presets, not in SKILL.md.
• Do not reach for user-facing branches or flags just because the design is underspecified; first try context, current artifacts, or a stronger default.
• Add a new user-visible branch only when the behaviors are genuinely distinct, user-meaningful, and unsafe to infer.
• 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.
• Keep SKILL.md concise. If the body approaches 200 lines, move detail into references/.

References

• 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/source-bound-records.md
• ../../shared/references/prescribed-path-self-test.md
• ../../shared/references/success-criteria-review.md
• ../../shared/references/external-capability-proof-ladder.md