write-agent-skill

Write Agent Skill

Goal

Create small, portable, well-triggered skills that teach repeatable agent behavior without becoming hidden project documentation, unsafe dependencies, or broad always-on instructions.

Core Principle

A skill is operational text and should be treated like a lightweight dependency. Its description decides whether the agent loads it, and its body changes how the agent acts. Design skills from examples, trigger boundaries, resource decisions, safety review, and validation before writing prose.

Use When

• The user asks to create, improve, split, merge, review, or validate a skill.
• A repeated non-obvious workflow needs procedural guidance.
• Skill trigger overlap or missing trigger coverage needs analysis.
• A skill eval should be added or revised.
• A behavior might belong in a skill, but could also belong in docs, a script, schema validation, or global agent instructions.
• A skill needs source-backed design research; use research-to-knowledge first or alongside this skill.
• A third-party or generated skill needs security, portability, or structure review before adoption.
• Skill files, references, scripts, permissions, or dependencies need a supply-chain or prompt-injection audit.
• A material skill update needs regression coverage for trigger behavior and output behavior.

Do Not Use When

• The content is a durable project fact, decision, architecture note, runbook, or research result.
• The behavior should apply to every task; use the repository entry instructions instead.
• A deterministic script or schema can enforce the rule more reliably.
• The task is a one-off request with no reusable workflow.
• The user only needs external research, not skill authoring; use research-to-knowledge.
• The task is only to install, run, or follow an existing skill without changing or auditing it.

Operating Modes

Mode	Trigger	Output
Classify	Unsure whether behavior belongs in a skill.	Destination: skill, docs, script/schema/test, handoff, entry instruction, or no artifact.
Create	New reusable procedural capability is justified.	Skill directory with SKILL.md plus eval.
Update	Existing skill behavior, trigger boundary, or resources must change.	Small patch plus updated evals covering behavior delta.
Boundary	Skill triggers too often, not often enough, or overlaps another skill.	Frontmatter/body/eval changes that protect routing.
Split/Merge	Skill size or overlap may justify restructuring.	Keep, split, merge, or delete recommendation with boundary evidence.
Secure	Skill, script, reference, dependency, or copied upstream package may be unsafe.	Security findings and patch or rejection.
Evaluate	Skill needs regression checks.	Should-trigger, should-not-trigger, edge-case eval prompts and validation results.