---
name: agent-skill-writer
description: "Writes or trims an agent skill file with a description that triggers at the right time, a workflow with finish lines and shallow references. Use when an agent skill file needs to be written or shortened so it loads at the right moment and stays easy to follow. Do not use for writing ordinary documentation or a one-off prompt that will not be reused. Related topics: AI, writing."
---

# Agent Skill Writer

Writes or trims an agent skill file with a description that triggers at the right time, a workflow with finish lines and shallow references.

## When to use

Use this skill when an agent skill file needs to be written or shortened so it loads at the right moment and stays easy to follow. Do not use it for writing ordinary documentation or a one-off prompt that will not be reused.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Draft the description first, with trigger words up front, the result it gives and a clear not-for line.
3. Cut anything the agent already knows, keeping only order of work, judgement calls and output shape.
4. Write the workflow as numbered steps that each end with a completion criterion.
5. Move bulky reference material to files linked one level deep from the skill.
6. Test the result against sample prompts that should and should not load it and report the changes.

## Inputs

- **Job the skill does** (longer free text)
- **Existing skill text** (longer free text)
- **Typical trigger phrases** (longer free text)
- **Neighbouring skills** (free text, e.g. "Jobs it could be confused with")
- **Reference material** (longer free text)
- **Mode** (choose one: Write new, Trim existing, Audit only)

## Output

The finished SKILL.md followed by a change list explaining each cut and edit, plus three prompts that should trigger it and one that should not.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Agent Skill Writer

Write or tighten a SKILL.md for the job below.

- Job the skill does: {{Job the skill does}}
- Existing skill text: {{Existing skill text}}
- Typical trigger phrases: {{Typical trigger phrases}}
- Neighbouring skills: {{Neighbouring skills}}
- Reference material: {{Reference material}}
- Mode: {{Mode}}

Start with the description, since it decides whether the skill loads: say what the result is and when to use it, front-load the trigger words, and add a line on what it is not for. Keep the body lean; the agent is already capable, so include only what it would not know: the order of work, judgement calls and the shape of the output. Write the workflow as numbered steps that each end in a completion criterion. Put long reference material in separate files linked one level deep from the skill, never chained. Use one consistent term per concept and no time-bound statements. Return the finished file, then a short list of what was cut or changed and why, and three prompts that should load the skill and one that should not.

## Pitfalls

- A vague description such as 'helps with documents', which never loads or loads for everything.
- Explaining basics the agent already knows, which burns context for no gain.
- Chaining reference files through each other, so the agent reads partial files and misses the rule.