Build a Claude Code Skill

Turn one repeatable workflow into a project skill that Claude Code can discover, follow, test, and improve.

For: developers, technical writers, operations leads, and teams that repeat the same structured task inside a codebase.

You will finish with: a valid skill folder, a complete SKILL.md, 5 practical tests, and a maintenance checklist.

What a Claude Code skill does

A skill packages instructions for a defined task. Claude can load it automatically when the skill description matches the request, or the user can invoke it directly with /skill-name.

The smallest useful skill is a folder with one SKILL.md file:

.claude/
└── skills/
    └── release-notes/
        └── SKILL.md

Project skills live in .claude/skills/<skill-name>/. Personal skills that should be available across projects live in ~/.claude/skills/<skill-name>/. A skill distributed through a plugin can live in that plugin's skills/ directory. See Anthropic's official skills documentation.

Supporting files are optional. Add references/, examples/, or scripts/ only when they make the workflow more reliable. Keep the main file concise. Anthropic recommends keeping SKILL.md under 500 lines and moving detailed reference material into supporting files.

Skill or CLAUDE.md?

Use the narrowest instruction surface that fits the job.

Do not create a skill merely to save a long prompt. Create one when the task has a stable trigger, sequence, output contract, and quality gate.

Step 1: define the job before the file

Write a one-sentence contract:

When the user asks for [trigger], use [approved inputs] to produce [specific deliverable], then verify [acceptance criteria].

For the worked example:

When the user asks for release notes, use the supplied diff or change summary to produce evidence-backed notes, then verify that every claim maps to an input.

Set 4 boundaries before writing:

Step 2: create the folder

Inside the project root, create this path:

.claude/skills/release-notes/SKILL.md

Use lowercase letters, numerals, and hyphens for a clear command name. Frontmatter is optional. If name is omitted, Claude Code uses the folder name. If you include name, keep it aligned with the folder so direct invocation stays predictable.

Step 3: write the complete SKILL.md

Copy this file as a working starting point. All frontmatter fields are optional. This example includes name for an explicit command name and description because a specific description helps Claude decide when to load the skill. If name is absent, the folder name becomes the skill name. A version field is not required.

---
name: release-notes
description: Create accurate release notes from a supplied git diff, pull request summary, issue list, or approved change log. Use when the user asks for release notes, a changelog entry, a launch summary, or a stakeholder update about software changes.
---

# Release Notes

Create concise, evidence-backed release notes for the stated audience.

## Required inputs

Collect:

- Product or repository name
- Release name or date
- Intended audience
- Git diff, pull request summary, issue list, or approved change log
- Known limitations or rollout notes, if any

If the release evidence or audience is missing, ask only for the missing input. Do not infer shipped functionality from a branch name, ticket title, or product roadmap.

## Process

1. Read all supplied evidence before drafting.
2. List the user-visible changes and map each one to its evidence.
3. Separate confirmed behavior from inferred impact.
4. Group confirmed items under Added, Changed, Fixed, or Known limitations.
5. Rewrite technical details for the intended audience without changing their meaning.
6. Remove empty sections and repeated claims.
7. Run the quality checks before returning the notes.

## Output format

Return:

1. Release title
2. A 1-paragraph summary of the release outcome
3. Added
4. Changed
5. Fixed
6. Known limitations
7. Verification note listing the supplied evidence used

Use bullets for individual changes. Start each bullet with the result, then add only the context needed to understand it.

## Evidence rules

- Include only behavior supported by the supplied material.
- Mark conflicting evidence as `[REVIEW NEEDED]` and explain the conflict briefly.
- Mark a missing detail as `[INPUT NEEDED]` rather than guessing.
- Do not invent performance gains, security improvements, compatibility claims, dates, customer quotes, or rollout status.
- Do not describe planned work as shipped work.

## Quality checks

Before returning the result, verify:

- Every change bullet maps to at least one supplied source.
- The audience can understand the summary without reading the implementation details.
- Technical names, versions, dates, and links match the evidence.
- Added, Changed, Fixed, and Known limitations are not used interchangeably.
- The notes contain no duplicate claims or unsupported outcomes.
- Any unresolved conflict or missing input is visible.

If a check fails, revise once. If the failure depends on missing or contradictory evidence, stop and request clarification.

Why this file works:

• The description states both the deliverable and the situations that should activate the skill.
• The inputs prevent the model from treating assumptions as release facts.
• The process is short enough to follow but specific enough to produce consistent work.
• The output contract creates a predictable page structure.
• The quality gate has observable pass conditions.

Step 4: test discovery and behavior

Test the skill in a safe sample project before trusting it with a real release. Claude Code detects changes to skills while a session is running. Restart only when the top-level skills directory itself did not exist when the session started and you created it during that session.

Use a small fixture for testing:

Product: Atlas Notes
Audience: workspace administrators
Release: 2.4

Confirmed changes:
- Added CSV export for audit events.
- Fixed the date filter resetting after page refresh.
- API export remains unavailable in this release.

An acceptable result should describe only those 3 facts, place the limitation in its own section, and identify the fixture as the evidence used.

Step 5: add supporting files only when needed

If the skill grows, keep the core workflow in SKILL.md and move stable details beside it:

.claude/
└── skills/
    └── release-notes/
        ├── SKILL.md
        ├── references/
        │   ├── product-terms.md
        │   └── release-policy.md
        └── examples/
            ├── customer-release.md
            └── internal-release.md

Tell Claude exactly when to consult a supporting file. A folder full of undocumented references is not a reliable system.

Troubleshooting

The skill does not activate automatically

Make the description more specific about the task and likely user wording. Test with a fresh session and confirm that the folder is inside .claude/skills/. Direct invocation with /release-notes helps separate a discovery problem from an instruction problem.

The skill activates too often

Narrow the description. Name the deliverable and exclude adjacent tasks. For example, release notes are not code review, roadmap planning, or a general summary.

The output varies too much

Replace broad adjectives with an output contract. Specify required sections, evidence rules, and a short pass checklist. Add one representative example only if the structure remains unclear.

Instructions conflict

Project instructions and the active user request may impose constraints beyond the skill. Remove duplicated repository-wide rules from the skill and keep task-specific guidance here. Review Anthropic's Claude Code best practices when deciding where instructions belong.

The file is becoming difficult to maintain

Split reference material into linked files. Keep the trigger, process, output, and critical safety rules in SKILL.md. Avoid a long archive of edge cases that the workflow cannot test.

Skill quality scorecard

Score each dimension from 0 to 2.

A score below 8 means the skill needs another revision before team use.

Finished-state checklist

• [ ] The folder name is clear, and any optional frontmatter name matches it.
• [ ] The description names both the task and likely activation phrases.
• [ ] Required inputs and stop conditions are explicit.
• [ ] The process produces a concrete deliverable.
• [ ] The full output contract is easy to inspect.
• [ ] Unsupported claims are prohibited.
• [ ] Automatic, direct, negative, missing-input, and conflict tests pass.
• [ ] Supporting files have a stated use.
• [ ] The main file remains concise and maintainable.

Continue on NEXAIUM

Use 36 Professional Prompts for Claude to find a repeatable workflow worth packaging. For a wider tool-selection system, continue with The Practical AI Stack.

Official references

• Extend Claude with skills
• Claude Code best practices
• Claude Code cheatsheet
• Anthropic skill-creator reference

Documentation was reviewed on 2026-09-04. Claude Code behavior and supported skill fields can change, so verify the current official documentation before distributing a skill broadly.