writing-skills

Writing Skills

Purpose

Create the smallest reusable skill that changes decisions or improves task execution without constraining unrelated work. Skill changes use behavior validation, not a code TDD route. This validation does not require loading aegis:test-driven-development.

Default Path

1. Establish Need And Ownership

• Name the reusable behavior gap, intended users/hosts, and non-goals.
• Check whether an existing skill, project rule, host adapter, or automated check already owns it. Prefer the smallest existing owner.
• For an existing skill, inspect its references, manifests or generated copies, discovery tests, and bundled resources before changing or retiring them.
• Create a skill only for reusable, non-obvious guidance. Keep one-off project conventions in the project owner and automate mechanical constraints when practical.

2. Record Behavior Before Editing

Use representative tasks, not questions that merely ask the agent to recite instructions.

• New skill: run a no-skill control.
• For an existing skill, run the current version first; add a no-skill ablation only when testing whether the skill itself needs to exist.
• Cover positive triggers, negative near-misses, and a pressure or application case appropriate to the skill type.
• Record decisions, missed or extra invocations, unsafe workarounds, evidence references, and unknowns. Do not treat line or byte counts as behavior proof.

If meaningful behavior cannot be evaluated, stop at needs-verification; do not claim that the skill is deployment-ready or capability-preserving.

3. Design The Minimum Instruction Surface

• Assume the agent is capable. Include only non-obvious context, decision criteria, safety boundaries, and steps whose omission caused an observed gap.
• Match specificity to risk: allow judgment for open work; use exact sequences only for fragile, permission-sensitive, or safety-critical operations.
• Keep the description concise, third-person, and discriminating. State the capability and when it applies; add an exclusion only when it prevents likely misrouting. Do not turn the description into a procedural shortcut.
• Keep the executable default path and non-omittable constraints in SKILL.md. Move substantial conditional detail to a direct reference and state the evidence trigger for reading it.
• Keep references one level deep where practical. Do not load every reference by default or duplicate its content in the main body.
• Add an example only when it materially stabilizes a decision or output. One representative example is normally enough.
• Keep portable method instructions host-neutral. Put host tool names, install paths, and UI choreography in their host-owned documentation.

The canonical repository shape is skills/<skill-name>/SKILL.md with only the supporting references, scripts, or assets the workflow actually uses. Use the repository's host docs or the target host's live specification for optional metadata instead of copying a vendor manual into the skill.

4. Make The Smallest Change

Address observed gaps and remove superseded duplication in the same slice. Preserve public attribution and any externally supported contract. When retiring an internal owner, fallback, or resource, compose aegis:anti-entropy-governance; do not leave a compatibility copy without dependency evidence.

Do not convert one model's phrasing, one historical incident, or a hypothetical edge case into a universal rule.

5. Validate The Candidate

Re-run the same positive, negative, and pressure/application scenarios under a comparable model, tool, and host configuration. Compare outcomes, not wording.

Also verify:

• frontmatter, name, and description parse on supported hosts;
• intended requests still discover the skill and near-misses do not;
• every conditional reference is reachable from an explicit trigger;
• changed scripts run successfully;
• retired files and instructions have no live references;
• repository workflow, boundary, packaging, and host checks relevant to the touched surface pass.

If behavior regresses, restore the missing obligation or narrow the change; do not add a second owner or fallback to mask it.

Scenario Selection

Skill type	Representative evidence
Discipline or safety	realistic pressure and authorization boundaries
Technique	application, variation, and missing-information cases
Pattern	recognition, application, and counter-example cases
Reference	retrieval, correct use, and common-gap cases

For a complex or high-risk skill where an independent evaluator adds confidence, read testing-skills-with-subagents.md.

Completion Record

Keep the result compact and auditable in natural prose or equivalent fields:

• behavior gap and canonical owner;
• baseline and candidate scenario results;
• retained and retired obligations/resources;
• trigger and reference checks;
• verification commands and uncovered hosts/models;
• status: verified, needs-verification, or blocked.

This is method-pack evidence, not authoritative completion or deployment approval.