Skill Authoring

---
name: skill-authoring
description: Create or revise managed agent skills with lean payloads, trigger evaluation, behavioral evidence, and pinned provenance.
license: Apache-2.0
disable-model-invocation: true
---

# Managed skill authoring

Use this explicit maintainer workflow to create, adapt, or substantially revise an agent skill. Edit only authoritative repository source, never a generated local projection.

## 1. Capture intent

Extract established requirements and corrections from the conversation before asking questions. Confirm only unresolved decisions:

- capability, user outcome, and non-goals;
- situations that should and should not activate it;
- inputs, outputs, side effects, tools, and permissions;
- objective and subjective success criteria;
- supported agents, modes, licensing, and payload constraints.

Collect realistic examples, edge cases, and near-misses. Trigger boundaries must be distinguishable and testable.

## 2. Prefer consolidation

Search the owned inventory first. Prefer improving an existing skill, folding a small rule into its domain owner, or adapting an audited source. Create a new skill only for a distinct reusable capability.

For upstream material, record commit, paths, license evidence, adaptations, and omissions. Keep provenance repository-only and ship one legally sufficient shared notice. Reject mutable guidance, undeclared services, redundant skills, and unreviewed scripts.

## 3. Minimize disclosure and payload

Descriptions may be always visible, `SKILL.md` loads on activation, and every reference, script, or asset is stored and synchronized even if unread.

Keep `SKILL.md` as the shortest complete workflow. Add a reference only when the activated workflow would otherwise be incomplete and state exactly when to read it. Add a script only for deterministic repeated work. Add assets only when required to produce the output.

Explicit maintenance utilities should use native non-model invocation metadata. Proactive domain skills need a concise description stating capability and trigger without keyword stuffing. Do not ship upstream examples, fixtures, viewers, generated guides, archives, build tooling, or provenance merely because they exist.

## 4. Define evidence before implementation

Create representative cases first:

- tasks where the skill should improve the outcome;
- near-misses where it should not activate;
- trust, file, network, and lifecycle boundaries;
- regressions that motivated the change.

For objective capabilities, assertions must check observable outputs or contract values and fail when implementation behavior breaks. Prompt text, source text, and UI copy are not behavioral evidence. Subjective design or writing quality needs blinded or human comparison.

For an existing skill, preserve its previous version as baseline. For a new skill, use the same task without the skill.

## 5. Compare fairly

Run with-skill and baseline cases against the same inputs, model family, tools, repository head, and time window. Capture outputs, assertions, subjective preference, duration and tokens when available, unexpected tool work, failure recovery, and activated payload cost.

Do not infer improvement from one favorable output. Investigate failures, revise one causal part, and rerun affected cases. Generalize rather than overfitting fixture wording.

Metered model evaluation, external consultation, and network services require current-user authorization. Long evaluation and CI work runs detached.

## 6. Evaluate activation

Use realistic should-activate and should-not-activate prompts, including ambiguous near-misses and competing skills. Evaluate description selection separately from body quality on held-out cases. Prefer the shortest description that preserves the intended boundary.

If the skill is explicit-only, verify it remains absent from model-visible discovery instead of optimizing automatic activation.

## 7. Account for runtime cost

Record before and after:

- model-visible description characters and activated bytes;
- runtime document count and per-agent fan-out;
- uncompressed and deterministic gzip release bytes;
- cache and bucket write set.

Every increase needs a named behavioral benefit. Replacements should normally reduce or hold payload. Shared notices have one owner.

## 8. Package in protected CI

Repository manifests are the runtime allowlist. Compilation, executable evaluation, packaging, and signed publication run through protected CI. Managed local syntax or lint checks are supplemental only.

Do not manually install the draft into user agent directories. Activate exact generated bytes only after contract CI and immutable publication succeed.

## Completion evidence

Report intent and trigger boundary, exact provenance, runtime inventory and modes, baseline comparison, prompt and seed deltas, CI and immutable release identities, and remaining bounded risk.