Writing great skills pruning pre prune

Writing Great Skills

Make a canonical Codex skill produce a predictable process through the smallest behavior-changing semantic surface. Predictability means the same process, not the same output.

Authority

Resolve one primary operation from the request before judgment or mutation:

• Audit inspects, reviews, compares, explains, or designs without write authority. It returns judgment only; exact replacement wording remains advisory and grants no permission to persist it.
• Author creates or edits an explicitly authorized canonical skill or skill-design artifact. It may change only that requested surface and the smallest directly affected proof or relationship surfaces.

A direct request to test whether wording changes behavior enters read-only behavior proof. Persisting any artifact requires Author authority; evaluation alone does not grant it.

The bundled skill-creator owns new-package scaffolding, generated metadata, and generic package mechanics. Writing Great Skills owns semantic quality for new and existing canonical skill instructions. It stops after canonical proof. Installation, installed mirrors, promotion, publishing, staging, commits, and pushes require their own owners and authority.

Resolve authority and source before judgment or mutation. Evaluate only the candidate the proof follows. These are the only universal ordering constraints.

Source And Coverage

Resolve the request, primary operation, canonical source, relevant current upstream, affected policy and pointers, callers and relationships, and available evidence before judgment or mutation.

For bounded work, follow only surfaces capable of changing the requested behavior. Include the canonical line, affected invocation policy, disclosed targets behind affected pointers, affected owners and relationships, and the smallest relevant structural or behavioral proof.

For a full audit, inventory and classify:

• every file in the canonical package, including policy, disclosed references, scripts, templates, assets, and schemas;
• current upstream and every recorded upstream decision;
• callers, routers, composers, handoffs, return consumers, and relationship records;
• every owned gate, input, output, mutation boundary, failure return, and completion criterion;
• structural tests, behavioral fixtures, current evaluations, and known gaps; and
• documentation or setup surfaces that publish or route the canonical skill.

Classify every inventoried item as affected, preserve, owned elsewhere, historical evidence, drift, or not applicable. Classify each relevant upstream difference as keep local, adapt, adopt, reject, or defer.

Installed mirrors and manifests are outside default coverage. Inspect mirrors only when installation-state evidence is explicitly requested. Audit reports the observed state and leaves repair to the installation owner.

Ownership And Relationships

Give each behavior one owner for its rule, admission predicate, authority, inputs, outputs, evidence, failure return, and completion. Another surface may name only its trigger, expected result, and return boundary.

Check every relationship through four facts: the callee that owns the behavior, the observable trigger that selects it, the authority preserved at the boundary, and the Return that resumes or stops the caller. Point to a foreign procedure instead of copying it.

Discoverable Authoring Contract

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

Make the applicable outcome, authority, current action or branch, Return, and completion criterion discoverable. These are behavior obligations rather than a named surface, mandatory heading sequence, 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 an adjacent false positive needs separating. Omit explicit-name reach, runtime procedure, identity already supplied by the body, and body-summary detail. Each trigger selects a distinct branch rather than renaming another trigger.

Keep universal and common-path behavior inline. Put branch-only reference behind a pointer that names both its target and its loading condition. Keep a concept's definition, rule, caveat, and failure consequence together. Split only for independent invocation, irreducible branch load, or observed premature completion that survives a sharper local criterion.

Use a leading word only when it recruits a useful prior and changes behavior against the current default. Define ambiguity once and repeat the word rather than its explanation.

Behavior-Preserving Pruning

Protect non-intuitive mechanics, semantic and safety contracts, authority, required outputs and proof, irreversible order, safe failure actions, and completion before cutting. Restore one owner before deleting duplicated foreign behavior. Remove stale exposition and disclose live branch-only material.

Ask of every instruction, "If I cut this, what behavior changes?" Delete the unit when the answer is none. Collapse repeated meaning into one rule and intentional emphasis into one leading word. State the positive target first; retain negation only for a necessary hard guardrail paired with the safe action.

Line count, word count, headings, and validator tokens are diagnostics rather than pruning verdicts.

Claim-Matched Proof

Use read-back and focused structural checks for exact bytes, links, policy, and machine contracts. Use caller/callee traces and representative relationship workflows for ownership and composition.

Load BEHAVIOR-EVALS.md when a direct test or claim says wording changes invocation, judgment, action, context loading, Return, or completion. Reject guidance when a realistic control does not exhibit its claimed failure.

Keep behavioral evidence independent: fixed tasks and rubrics, fresh contexts, no candidate language or prior conclusions in controls, and root-held judgment. Ambient collaboration policy owns dispatch mechanics.

Return

Return complete, partial, or blocked with resolved authority and coverage.

Audit also returns the verdict, impact-ordered findings, useful exact candidates, deliberate non-changes, behavior at risk, and evidence limits. Author also returns changed canonical surfaces, behavior added, changed, or removed, structural, relationship, and behavioral proof, preserved unrelated state, deliberate non-changes, and residual risk.

Completion

Complete only when coverage is classified; every affected invocation surface, owner, relationship, pointer, gate, input, output, mutation boundary, failure 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.