---
name: write-agent-skill-prompt
description: A prompt that has your AI agent turn a task you keep repeating into a reusable SKILL.md agent skill - clear name, a description with Use when triggers, short numbered steps, gotchas and a done check - then test that it loads. Use when the user wants to create a skill, write a SKILL.md, save a workflow for Claude Code or Cursor, or improve an existing skill.
license: CC-BY-4.0
metadata:
  category: coding-prompts
  tags: "skills,agents,docs,workflow"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-31"
  status: published
  aliases: "skill-creator,create-skill,write-skill"
---

# Write an agent skill (prompt)

A skill is a folder with a `SKILL.md` file. The agent reads its short description all the time and loads the full steps only when a task matches. This prompt turns something you keep explaining into a skill the agent picks up on its own.

## When to use
- You keep typing the same instructions for a task, like releasing or writing tests.
- You want to save a working process so any agent can repeat it.
- An existing skill is not triggering, or the agent follows it badly.

## Steps
1. Do the task once with the agent, so the steps are fresh in the chat.
2. Paste the prompt below and name the task.
3. Answer its questions, review the draft, then try a fresh chat with a normal request to see it load.

## Prompt
```text
Help me turn this task into a reusable agent skill (a SKILL.md file).

Task: [describe the task, or say "the one we just did"]

1. Interview me first, one short round: what triggers this task, what the finished
   result looks like, what usually goes wrong, and which tools or files it touches.
2. Pick a name: lowercase-with-hyphens, verb first (e.g. deploy-docs-site), max 64 chars.
   The folder name must equal the name.
3. Write the frontmatter:
   ---
   name: <name>
   description: <what it does in one sentence>. Use when <2-3 concrete triggers in the
     words a user would really type>.
   ---
   The description is the only part the agent sees before choosing the skill.
   Make it specific; vague descriptions never trigger.
4. Write the body, under 300 lines:
   - When to use (2-4 bullets)
   - Steps: numbered, one action each, short sentences, exact commands in code blocks
   - Gotchas: the mistakes we actually hit
   - Done when: checks that prove it worked
   - Example prompt
5. Move long reference text or scripts into files next to SKILL.md
   (references/, scripts/) and link them. Keep SKILL.md lean.
6. Never put real secrets, API keys, tokens or passwords in the skill. Use placeholders
   like <YOUR_API_KEY> and say where the real value lives (.env, secret manager).
7. Show me the full draft. After I approve, save it to the skills folder for my tool:
   Claude Code ~/.claude/skills/<name>/, Cursor .cursor/skills/<name>/,
   others .agents/skills/<name>/.
8. Suggest 3 test requests that should trigger it and 1 that should not.
```

## How to adapt
- Works with Claude Code, Cursor, Codex, or any tool that reads the open SKILL.md format.
- Improving a skill instead of writing one? Paste the old SKILL.md and say "tighten this and fix the triggers".
- Team skills go in the repo (`.agents/skills/`) so everyone gets them. Personal ones go in your home folder.
- Before writing your own, search TheSkillVault: a tested skill may already exist.

## Done when
- The skill has a verb-first name, a description with "Use when" triggers, numbered steps and a done check.
- A fresh chat with a normal request loads it without you naming it.

## Example prompt
"We just set up preview deploys together. Turn that into a skill so you do it the same way next time."