# Write a skill an agent can find and follow

Canonical: https://shivanshsen.com/blogs/writing-effective-agent-skills

Give a repeated task a clear trigger, a short workflow, an output contract, and a boundary.

I can keep adding rules to a skill until its SKILL.md reads like a team handbook. The better test is smaller: can it recognize the right request, take the right steps, and leave a result I can check? A useful skill makes a repeated task more dependable without claiming authority the agent does not have.

An Agent Skill is a directory with metadata, instructions, and optional resources. The agent can use the metadata to decide when to load it, then read extra files when the task needs them. The [Agent Skills specification](https://agentskills.io/specification) defines the file format; the [Claude Platform overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) describes how Claude uses its parts.

## Start with a task that has a real gap

Before writing, name the repeated task and the mistake you want to prevent. For this example, the team drafts release notes from merged pull requests. The hard part is separating user-facing changes from internal work and from claims the source does not support.

Suppose the release includes three changes: PR #41 fixes exported filenames that contain spaces; PR #42 renames an internal helper; PR #43 changes a timeout but does not explain its effect. The agent must not turn that last fact into “faster failures” or “a better experience.” It must tell the release owner what remains unknown.

That gives the skill a job: prepare a release-note draft from the selected release inputs, use only evidence in those inputs, and leave publication to a person. “Help with releases” is too broad. “Draft release notes from merged pull requests for a named release” gives the agent a task it can recognize.

## Make the trigger specific

The required frontmatter fields are `name` and `description`. The name is short and matches the skill directory. The description says what the skill does and when to use it. For example: `Drafts release notes from merged pull requests or a release branch. Use when preparing a named software release for review.` The [specification](https://agentskills.io/specification) sets the field limits; Anthropic’s [authoring guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) recommends concrete terms that help the agent select the skill.

A minimal entry point can make the contract explicit. This is an example to adapt to the team’s release policy:

```markdown
---
name: release-notes
description: Draft release notes from merged pull requests for a named release. Use when preparing a release draft for review.
---

# Draft release notes
1. Confirm the release range and intended audience.
2. Read the supplied merged PRs; inspect diffs when the impact is unclear.
3. Include verified user-facing changes with a source link.
4. Omit internal refactors unless the release policy requests them.
5. Flag missing or conflicting evidence under Owner check.
6. Return a Markdown draft. Do not publish, tag, or edit a live changelog.
```

Write the trigger for the request the agent should handle, then try a request that should not activate it. “Draft notes for version 2.4 from the merged PRs” should match. “Explain how our changelog works” may need an answer, but not the release-note workflow. A description that matches every mention of a release will crowd out other skills; one that only matches an exact phrase will miss ordinary requests.

## Turn the task into steps

The main instructions should tell the agent what to inspect and in what order. Name the release range or source branch. Gather the merged pull requests in that range. Read the linked change descriptions or diffs when the title is not enough. Classify each change for the intended audience. Draft the notes, then check each line against its source.

Keep rules near the step where they matter. Say whether internal refactors belong in public notes. Say what to do when a description is incomplete. Say which source wins when a pull request title and diff disagree. Do not repeat facts the agent can find in the repository or policy reference.

## Show the result and the stopping point

A short output contract removes guesswork. Ask for a draft grouped under “Added,” “Fixed,” and “Changed,” with one supported change per bullet and a pull-request link. Omit empty sections. Keep the wording understandable to the release’s audience. Include an “Owner check” section only when evidence is missing or conflicts.

For the three example pull requests, the draft might say: “Fixed — exported filenames now handle spaces correctly (PR #41).” The internal helper rename in PR #42 stays out of the public notes, unless the release policy asks for an internal section. PR #43 gets an owner check: its description names a timeout change but not the effect. That is a useful draft because the agent has not filled the gap with a guess.

Put the boundary in plain language: save or return a draft for review; do not edit the published changelog, tag a release, or post notes unless the user asks. If the agent cannot access a pull request, report that instead of silently skipping it. An output format can guide the work, but it cannot grant permission.

## Check selection and output

Try at least three release inputs: a clear user-facing fix, an internal-only rename, and a change with an unstated impact. Check that the skill includes the first, filters or labels the second according to policy, and flags the third. Also test a request that should not trigger it. Anthropic recommends building evaluations before expanding the instructions; the [authoring guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) describes that loop.

If the tests expose a gap, add only the rule or reference that fixes it. The companion guide to [structuring Agent Skills](https://shivanshsen.com/blogs/structuring-agent-skills) shows where those details belong. A separate note on [evaluating Agent Skills](https://shivanshsen.com/blogs/evaluating-agent-skills) covers the test set.

## Sources

- https://agentskills.io/specification

- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices