A skill file is a document that teaches an agent how to do one specific thing reliably. Not a system prompt — a skill. It's modular, reusable, and composable.
The difference: your system prompt defines who the agent is. A skill file defines how it does something.
What a Skill File Is
When you want an agent to perform a recurring task — write a blog post, review a pull request, triage an issue — you have two options:
- Add it to the system prompt and bloat it
- Write a skill file and reference it when needed
Skill files keep your system prompt clean. They can be loaded on demand, shared across projects, and updated without touching your core configuration.
The Template
# [Skill Name]
## Purpose
One sentence. What does this skill do and when is it used?
## Trigger
When should this skill activate? Explicit request keywords, context signals, or both.
## Input
What does this skill expect? Structured parameters, free-form text, file references?
## Process
Step-by-step instructions. Use numbered lists.
Be specific — "be helpful" is not a step.
## Output
What should the result look like? Format, length, tone, structure.
## Examples
One minimal example: input → output.
## Constraints
What this skill must NOT do. Edge cases. Escalation rules.
A Real Example: Blog Post Draft
# blog-post-draft
## Purpose
Draft a structured blog post from a brief outline or topic prompt.
## Trigger
User provides: topic, audience, desired length, and tone.
Keywords: "write a post", "draft a blog", "create an article".
## Input
- Topic: required
- Audience: required (e.g., "developers", "non-technical founders")
- Length: optional (default 600 words)
- Tone: optional (default "clear and direct")
- Outline: optional
## Process
1. Identify the single key insight the post should deliver.
2. Write a headline that leads with that insight, not with the topic.
3. Open with the problem or question the reader has — no "In this article" openers.
4. Structure the body: one idea per section, short sections preferred.
5. Close with a concrete takeaway or next action.
6. Review: cut any sentence that doesn't earn its place.
## Output
- Markdown format
- H2 headers for sections
- No filler phrases ("It's important to note that...", "In conclusion...")
- Final word count within ±10% of target
## Examples
Input: "Topic: using context windows effectively, Audience: developers, Length: 500 words, Tone: practical"
Output: A 500-word post with a headline like "Context Windows Are Buffers, Not Libraries" — practical, no fluff.
## Constraints
- Do not fabricate statistics or cite sources you cannot verify
- Do not add a "disclaimer" section unless explicitly asked
- If the topic is outside your knowledge, say so before drafting
Design Principles
One skill, one job. Don't write a skill that reviews and rewrites and formats. Split it. Focused skills compose better than multipurpose ones.
Triggers matter. Vague triggers ("when the user asks for help with writing") create ambiguity. Specific triggers ("user explicitly says 'review my draft'") fire reliably.
Description beats rules. Describing what good output looks like is more powerful than listing rules about what to avoid. Show the target, not just the guardrails.
Examples are load-bearing. Even a single input/output example anchors the skill's behavior better than three paragraphs of instructions. When in doubt, add an example.
When to Write a Skill File
Write a skill file when:
- You find yourself giving the same detailed instructions in multiple conversations
- A task has clear, repeatable structure
- You want consistent output across different agents or projects
Don't write a skill file for one-off tasks or experiments. The overhead isn't worth it until a pattern repeats.
Skill files are leverage. The best ones get used hundreds of times.
Comments 0