Not every repeated prompt deserves an agent skill

If you keep telling your coding agent “review the diff, check security, run these tests, and give me a report”, you are not prompting any more. You are maintaining a workflow by hand. An agent skill lets you write it down once: a SKILL.md file that Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity can all read.

This part starts a step before the SKILL.md. Which repeated work deserves a skill? What should stay a normal prompt? And how do you keep a skill useful once the code around it changes? Part 1 placed skills among the six layers of a coding agent project. Part 3 covered when a skill beats an agent, MCP or a hook.

Claude Code is the worked example. The tool behaviour below comes from each tool’s official docs and the Agent Skills specification, last verified on 4 October 2026; none of it was tested for this post.

Repeated prompting is a workflow you keep by hand

The first time you explain a review process to an agent, it is a prompt. Tomorrow you explain it again. Next week you explain the same steps, tweak the wording, and explain them once more. By then the workflow has become reusable knowledge, and it only exists in old chats.

once → again → same steps explained → refine → again → skill

My rule: repeatability plus a stable process makes a good skill candidate. Don’t create a skill after the first repetition. Wait until the steps have come up several times and stopped changing. The Agent Skills best practices point the same way: “Effective skills are grounded in real expertise”. Do a real task with the agent first, then pull the reusable pattern out of it.

What goes inside a skill folder

A skill packages more than instructions: examples, references, scripts or tools, and the expected output go in it too. The specification gives the folder its shape: a required SKILL.md plus optional scripts/, references/ and assets/ folders. An example code-review skill might look like this:

code-review/
├── SKILL.md       # what to inspect, in what order, how to report
├── references/    # severity guide, what to ignore
└── scripts/       # helpers the review can run

Only name and description are required in the frontmatter of SKILL.md. The agent keeps the short description in view all the time and loads the rest when the skill is used, as Part 1 explained. So the difference shows up on every task:

Where a skill stops and an agent or a hook starts

A skill answers “how should this workflow be performed?”. An agent answers “who should perform this responsibility?”. So one main agent can carry code-review, security-review and testing skills itself, or hand the work to separate code-reviewer and security-reviewer agents. A skill does not need another worker, although Claude Code can run one in a sub-agent with context: fork (skills docs).

A check that must run every time belongs in a hook or CI, not a skill. A skill is chosen by the model from its description, and VS Code’s agent skills docs say discovery “does not guarantee that it invokes a skill for every relevant prompt”. Part 3 has the full comparison.

The five parts of a good skill

A good skill has five parts: trigger, context, process, evidence and output. Here they are for the code-review example:

The evidence a review needs is the subject of Part 4.

The trigger lives in the description, and the description is what the agent matches your request against. Codex’s skills docs put it well: “Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened.”

A skill also needs boundaries: what it does, when it is used, its inputs, its process, its output, and what it does not do. Without them it grows into one giant instruction dump, which is the bloated instructions file again in a new folder. The specification says “Keep your main SKILL.md under 500 lines”, and the best practices warn that “Overly comprehensive skills can hurt more than they help”.

Domain knowledge can become a skill

A skill can also carry the review habits of your own stack. Take a hypothetical example: reviewing a Business Central extension written in AL, the language Microsoft uses for Business Central. An experienced reviewer might walk through it in this order:

AL code → object structure → naming and conventions → permissions
        → error handling → performance → tests → diff → findings

Written down as a business-central-code-review skill, that order stops living in one reviewer’s head, and every review the agent does follows it. Swap in your own stack and your own review order; the shape is the same.

your experience → explicit workflow → skill → reusable AI capability

Package a meaningful workflow, not a single action

Some repeated work is too small for a skill, and some is too rare or still changing. Keep those as normal prompts. A one-line request does not need a folder:

Too big is a problem as well. The best practices compare scoping a skill to “deciding what a function should do”. Scoped too narrowly, several skills load for one task. Scoped too broadly, a skill becomes “hard to activate precisely”. Antigravity’s skills docs say it in one line: “Each skill should do one thing well.”

Two prompts: find skill candidates, then review them

Prompt 1: find skill candidates

Use Prompt 1 when you suspect you keep repeating yourself in a repository. It asks the agent to propose candidates, say when a skill is not justified, and wait.

Analyse this repository and identify workflows
that are repeated, structured, and good candidates
for reusable AI Skills.

For each candidate, report:

1. Workflow name
2. How often it appears
3. Current manual process
4. Repeated instructions/context
5. Inputs required
6. Expected output
7. Existing scripts/tools that could be reused
8. What should remain human-controlled
9. Whether a Skill is actually justified

Do not create any Skills yet.
Never print, expose or commit secret values.

Prefer simple workflows with clear boundaries.

If a workflow is too unstable, too rare, or too small,
recommend keeping it as a normal prompt instead.

Then propose the highest-value Skill candidates
and wait for approval.

Prompt 2: review a skill like production code

Use Prompt 2 on any skill before you rely on it: your own, a teammate’s, or one you downloaded.

Skill: <path to the skill folder>

Review this Skill as if you were reviewing production code.

Check for:

- unclear trigger conditions
- unnecessary instructions
- duplicated project rules
- missing inputs
- ambiguous steps
- unverifiable requirements
- excessive context
- unnecessary tool usage
- missing failure handling
- output ambiguity
- security risks
- maintenance problems

Suggest only changes that materially improve
reliability, clarity or maintainability.

Do not rewrite the Skill yet.
Return findings first.

Run it again whenever the workflow behind the skill changes.

A starter skill for code review

Here is a starter to copy. Save it as code-review/SKILL.md, because the specification says the folder name must match name.

---
name: code-review
description: Review code changes for correctness, maintainability, security and project conventions. Use when reviewing a pull request or significant code change.
---

# Code Review

## Purpose

Review the requested code change without modifying the implementation.

## Inputs

- Git diff
- Relevant project files
- Applicable project rules
- Tests

## Workflow

1. Understand the intended change.
2. Read the relevant code.
3. Inspect the diff.
4. Check project conventions.
5. Check correctness and edge cases.
6. Check security implications.
7. Check test coverage.
8. Report findings with evidence.

## Severity

- Critical
- High
- Medium
- Low
- Informational

## Output

Return:

- Summary
- Findings
- Severity
- Evidence
- Recommended action
- Remaining uncertainty

## Boundaries

Do not modify code unless explicitly requested.
Do not invent requirements.
Do not report speculative issues as confirmed findings.

Keep the description on one line, or indent any lines after the first. Wrapped lines that start at the left margin are not valid YAML. In Claude Code, a project skill called code-review replaces the bundled /code-review command (docs). Give yours another name if you want to keep the built-in one.

How to stop a coding agent from running a skill on its own

Part 3 lists where six coding agents keep skills, and most of them read .agents/skills/. A skill that edits or deploys is one you may want to run only by name. Each agent has its own switch:

Each row comes from that tool’s own docs, last verified on 4 October 2026; none of them was tested for this post.

A checklist before you save a skill

• The steps have come up several times and stopped changing.
• It packages a whole workflow, not a single action.
• The description says what it does and when to use it, trigger words first.
• It names its inputs, its steps, the evidence it needs and its output.
• It says what it does not do.
• SKILL.md stays under 500 lines; details go in references/.
• A check that must run every time is a hook or CI instead.
• Someone reviews it when the workflow changes.

Treat skills like code: review them when the workflow changes

A skill is an engineering asset, and like code it goes stale. When the architecture changes and the skill does not, the agent follows an old process and makes wrong recommendations.

identify → define → implement → test → use → observe failures → refine ↺

The best practices say “The first draft of a skill usually needs refinement.” They suggest running it on real tasks, then asking: “what triggered false positives? What was missed? What could be cut?”

Skills from other people need the same review before you install them. GitHub’s skills docs warn that skills “may contain prompt injections, hidden instructions, or malicious scripts”. Its CLI docs add that pre-approving shell or bash in a skill’s allowed-tools field removes the confirmation step for terminal commands. The starter above leaves allowed-tools out. How much an agent may do without asking is the subject of the next part of this series: permissions, sandboxing and approval gates.

Quick answers

What is an agent skill?

An agent skill is a folder with a SKILL.md file that packages a repeated workflow for a coding agent: instructions, plus optional scripts, references and assets. Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI and Google Antigravity all read the open Agent Skills format.

When should you turn a prompt into a skill?

A prompt is worth turning into a skill when you have explained the same steps several times and those steps no longer change. A workflow that is rare, unstable or a single small action is better kept as a normal prompt.

How long should a SKILL.md file be?

The Agent Skills specification recommends keeping the main SKILL.md under 500 lines. Detailed reference material goes in separate files that load only when the agent needs them.

What makes a good skill description?

A good skill description says what the skill does and when to use it, with the main use case and trigger words first. Coding agents match your request against the description to decide whether to load the skill.

Do coding agents use skills automatically?

Most coding agents load a skill on their own when a request matches its description. Several also let you call it by name, such as /name in Claude Code and $ in Codex. Gemini CLI asks you to approve a skill before it activates.

More on AI coding is in the AI category.