Writing great skills

Writing Great Skills

Predictability: same process, variable output.

Authority

Select one operation from the request:

• Audit: judge read-only. Exact candidate wording remains advisory.
• Author: edit only the requested canonical skill or skill-design artifact and directly affected proof or relationship surfaces.

A direct behavior test is read-only; any persisted artifact requires Author authority. The bundled skill-creator owns new-package scaffolding and metadata mechanics. Writing Great Skills owns semantic quality and stops after canonical proof; installation and delivery remain with their owners.

Resolve authority and source before judgment or mutation. Proof follows the candidate it evaluates. No other universal step order is required.

Coverage

Resolve the target, operation, canonical source, relevant current upstream, affected surfaces, relationships, and available evidence. Bounded work follows only surfaces capable of changing the requested behavior, including affected policy, pointers, owners, and the smallest relevant proof.

For a full audit, read and classify the complete canonical package; upstream and recorded decisions; callers and composition; owned gates, outputs, mutations, failure branches, and completion; tests, evaluations, and gaps; and routing or publication surfaces. Classify each item affected, preserve, owned elsewhere, historical evidence, drift, or not applicable, and each upstream difference keep local, adapt, adopt, reject, or defer.

Inspect mirrors only when installation-state evidence is explicitly requested. Report what is observed and leave repair to the installation owner.

Ownership

Give each behavior one owner for its rule, admission, authority, inputs, outputs, evidence, failure return, and completion. Preserve each relationship's callee, observable trigger, authority, and Return. Point to foreign procedure instead of copying it.

Authoring Contract

Load GLOSSARY.md when invocation, information hierarchy, leading words, pruning, or completion meaning affects the work; a full audit reads it completely.

Make the applicable outcome, authority, action or branch, Return, and completion discoverable without imposing a named surface, mandatory headings, or fixed order.

Treat an implicitly invocable description as an always-loaded routing predicate. Name observable request or caller triggers, add the closest exclusion only when needed, and omit explicit-name reach, runtime procedure, and body-summary detail. Each trigger selects a distinct branch rather than renaming another.

Keep common-path behavior inline. Put branch-only reference behind a pointer that names its target and loading condition. Co-locate each concept. Split only for independent invocation, irreducible branch load, or observed premature completion that survives a sharper criterion.

Behavior-Preserving Cuts

Protect non-intuitive mechanics, semantic and safety contracts, authority, proof, irreversible order, safe failure actions, and completion. Restore one owner, remove stale exposition, and ask of every instruction: "If I cut this, what behavior changes?" Delete no-ops, collapse duplicated meaning into one rule or leading word, and disclose branch-only detail. State the positive target first; retain negation only for a necessary guardrail paired with the safe action.

Claim-Matched Proof

Use read-back and focused structural checks for exact bytes or machine contracts, relationship traces for ownership, and BEHAVIOR-EVALS.md when a direct test or claim says wording changes invocation, judgment, action, context loading, Return, or completion. Reject candidate guidance when a realistic control does not exhibit its claimed failure.

Keep behavioral controls uncontaminated: fixed tasks and rubrics, fresh contexts, no candidate leakage, and root-held judgment. Ambient collaboration policy owns dispatch mechanics.

Return

Return complete, partial, or blocked with authority and coverage. Audit adds the verdict, impact-ordered findings, useful exact candidates, deliberate non-changes, behavior at risk, and evidence limits. Author adds changed canonical surfaces, behavior added, changed, or removed, proof, preserved unrelated state, deliberate non-changes, and residual risk.

Completion

Complete when coverage is classified; every affected invocation surface, owner, relationship, pointer, gate, output, mutation boundary, Return, and completion criterion has one home; upstream differences are decided; claimed behavior has current proportionate evidence; canonical checks pass or skips are named; unrelated work is preserved; and Return stops before installation or delivery.