Writing Skills

Process

1. Load the governing reference. Before drafting, read and follow writing-great-skills and its complete GLOSSARY.md. First run cd '<loaded-skill-directory>' && pwd -P with this loaded file's directory; resolve links from the printed physical base, not the workspace or symlink alias. This step is complete only after the full reference has been read and its discovery, information-hierarchy, splitting, completion, and pruning rules govern the planned skill.

2. Establish requirements and authority. Read-only inspection may precede the adaptive Delivery mode gate; drafting may not. Honor any semantic topology and availability choices already established, and ask only for a materially unresolved dimension. An untracked request or exactly one selected Ticket stays with its current conversational owner, whether the maintainer stays or authorizes work while away. Absence alone adds no readiness, Prompt Audit, dispatcher, or approval step.

   Resolve all of these questions:

   • What task or domain does the skill cover?
   • Which use cases must it handle?
   • Does it require executable scripts, instructions, or both?
   • Which reference materials must it include?
   • Will it remain user-only by default, or does it qualify as agent-discoverable under Description and Discovery?
   • If it handles Tickets, does it keep one request or Ticket with its current owner, reserve dispatch for multiple selected Tickets, distinguish readiness from execution authority, and preserve the authorized stopping point?
   • If it selects among several user-only skills, is it a skill-selection Router Skill rather than a Ticket dispatcher?
   • If it launches model-selectable workers, does its caller compose model-routing rather than copy the parent's model or maintain a separate model table?

   Resolve established requirements from the accepted conversation, Ticket, governing sources, and repository conventions. The responsible agent owns drafting and material contract updates. Ask the available maintainer only about genuinely missing material requirements; in Unattended work, report the specific blocker. A delegated helper returns unresolved requirements to its caller. Material steering updates durable authority and applicable gates before affected drafting.

   This step is complete only when every requirement is resolved or the applicable terminal blocker has been returned and drafting has stopped.

3. Draft the skill. Create:

   • a SKILL.md containing the instructions required by every branch;
   • linked reference files when the governing information hierarchy assigns branch-specific reference behind a context pointer;
   • utility scripts when any condition under When to Add Scripts applies.

   Follow Splitting and Disclosure. This step is complete only when the draft represents every accepted use case and every required bundled resource exists and is directly referenced.

4. Verify and review. Apply every item in the Review Checklist, checking the decision-bearing content of every bundled resource against every accepted use case. A skill behavior change receives one fresh independent adversarial code-review pass with the concise current contract, applicable governing sources, complete candidate, and verification instructions. Apply its adversarial contract: the reviewer reports every supported problem in the single planned pass; the responsible writer follows code-review's one-way handoff, adjudicates every finding, applies in-scope corrections, and verifies them without seeking reviewer approval of the corrections. Purely editorial documentation may be self-reviewed. A delegated helper returns its draft and evidence to the responsible owner for that review. User feedback may supplement but never substitute for required independent review.

   The skill is complete only when every accepted use case and every decision-bearing bundled resource is accounted for, every checklist item passes, and the applicable review is resolved.

Skill Structure

Every skill requires skill-name/SKILL.md. Add REFERENCE.md, EXAMPLES.md, or scripts/helper.js under the same skill directory only when the conditions below require them.

SKILL.md Template

---
name: skill-name
description: One-sentence description of the operations or outcome.
disable-model-invocation: true
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Ordered processes and completion checklists]

## Advanced features

[Context pointer: See [REFERENCE.md](REFERENCE.md)]

Description and Discovery

Every skill requires a description.

• User-only is the default. Set disable-model-invocation: true. Write one command-facing sentence that identifies the capability; this metadata is excluded from the agent's system context.
• Agent-discoverable requires observed use that demonstrates a need for autonomous selection plus maintainer approval of the permanent context load. Omit disable-model-invocation. State the capability first, followed by one trigger for each distinct branch that should select the skill.

A loaded skill may compose a user-only skill through a direct relative file pointer under the loaded writing-great-skills discovery rules; composition does not require a visible discovery entry. A Router Skill selects an installed skill or disclosed reference to load; it does not own Mission identities, topology or Ticket dispatch. dispatch-tickets owns Mission continuity, eligibility decisions within the selected queue, and delivery verification; it supervises multiple selected Tickets, including their time and progress, without writing code. implement loads orchestrate in the current conversation for one Ticket. orchestrate is that owner's procedure for implementation, independent review, corrections, and delivery, not another coordinator to launch. Maintainer availability does not change topology or ownership. Entry checks selected-work authority, applicable gates, and actual capabilities.

Every description must:

• contain no more than 1024 characters;
• lead with a base-form capability verb;
• identify the operations or outcome the skill provides;
• omit automatic trigger phrasing when the skill is user-only.
• Agent-discoverable example: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
• User-only example: Extract text and tables from PDF files, fill forms, and merge documents.
• Invalid example: Helps with documents. identifies neither an operation nor an outcome.

When to Add Scripts

Add a utility script when at least one condition applies:

• the operation is deterministic, such as validation or formatting;
• the same code would otherwise be generated repeatedly;
• errors require explicit handling.

Splitting and Disclosure

Use the writing-great-skills information hierarchy for progressive disclosure: keep instructions required by every branch in SKILL.md, and move branch-specific reference behind a direct context pointer.

For a skill or sequence split, apply the loaded writing-great-skills splitting conditions.

Line count, a separate domain, or rarity is not split evidence. Treat excess length as sprawl and apply the information hierarchy before considering a governed split.

Review Checklist

After drafting, verify every item:

• Every accepted use case maps to explicit instructions.
• At least one concrete input/output or interaction example is included.
• Every ordered step has a checkable completion criterion, exhaustive where coverage is required.
• disable-model-invocation: true is present unless the skill qualifies as agent-discoverable under Description and Discovery.
• The description satisfies the format rules; an agent-discoverable description contains one trigger per distinct branch.
• Process instructions avoid time-sensitive assumptions, expiring URLs, and unpinned latest values. An explicitly requested maintained compatibility/model catalog is isolated in a sourced reference with its verification basis, rather than copied into workflow instructions.
• Each concept has one term, used consistently; Router Skill wording cannot imply Ticket-dispatch ownership.
• Ticket routing keeps single-request ownership in the current conversation, reserves dispatch for multiple Tickets, and does not add gates merely because the maintainer leaves. Required readiness remains eligibility, not execution authorization.
• Every skill or sequence split has the required discovery or observed-sequence evidence.
• Every bundled context pointer links directly to its target, with no chained bundled reference.
• The decision-bearing content of every bundled resource has been inspected and agrees with every accepted use case and governing source.