skill-authoring

name	skill-authoring
description	Use when creating, editing, renaming, migrating, trimming, reviewing, or testing an agent SKILL.md. Helps make the skill triggerable, concise, operational, scoped, and fresh-agent tested.

Skill Authoring

A good skill teaches an agent when to load it, what to do next, and what mistakes to avoid. Keep it small enough to read fully and specific enough that a fresh agent can act without guessing.

Work in this order:

1. Identify the agent behavior the skill should change.
2. Define the trigger.
3. Write the shortest operational body that preserves the important behavior.
4. Remove background, history, and advice that is not needed at runtime.
5. Test it with a fresh agent and revise where it stumbles.

Trigger

Agents usually select skills from the name, description, and path before reading the full file. Write the description as the primary trigger.

Write the description as "Use when..." plus the phrases people actually say. Front-load the trigger words so the right use case is obvious immediately.

Body

Make the body easy to execute:

• Put the normal workflow first.
• Use bullets or numbered steps for runtime instructions.
• Say what each command or workflow does in plain words.
• Be precise where mistakes are costly.
• Leave flexible choices flexible.
• Remove aliases, history, defensive caveats, and extra notes.
• Include only what is required to do the task correctly.
• If something is irreversible, say so.
• When behavior changes, update the skill in the same commit.

Source

Create skills from observed use:

• Repeated context you give agents.
• Mistakes agents actually make.
• Workflows agents skip or perform out of order.
• Tool behavior agents cannot infer from names or help text.

Do not document imagined edge cases. Add rules when real usage proves they are needed.

Trimming

When you trim, diff against the version you replace and account for every drop. Anything not load-bearing can go: reference detail, code, redundancy, history, caveats. The agent can always read --help or the source for more. Only operational knowledge has to survive.

Style

Write for an unbiased reader:

• Assume the agent has no prior context about your system.
• State what is true, not what to avoid.
• Do not introduce a wrong option just to reject it.
• Prefer direct instructions over explanation.

Dependencies

Skills support each other. If a skill requires another skill, declare the dependency in frontmatter:

requires: [lac]

Scope

Keep the skill small. If it tries to cover a large CLI or many unrelated workflows, split it into narrower skills or consolidate the underlying commands.

Do not turn missing tool behavior into permanent skill policy. If the tool can make the right behavior obvious or automatic, improve the tool and keep the skill simple.

When renaming or replacing a skill, migrate aggressively. Update active references and delete the old skill unless compatibility is required.

Testing

Test with a fresh agent:

• Give it realistic prompts that should and should not trigger the skill.
• Check whether it selects the skill from the description.
• Check whether it follows the body without extra explanation.
• Revise the description or body where it stumbles.

Use agent-dogfeed when it fits the workflow.