Claude Skills — Reusable Workflows for Claude

Claude Skills — Reusable Workflows for Claude

Claude Skills are reusable instruction packages that teach Claude how to handle a specific workflow, domain, style guide, or multi-step task. Instead of explaining the same process in every chat, you package the instructions once and let Claude load them when they are relevant.

Skills are useful when you want Claude to behave consistently across repeated tasks:

• Generate a report in your organization’s format
• Review code using your team’s standards
• Produce a PowerPoint, Word document, spreadsheet, or PDF
• Follow a specific deployment checklist
• Use project-specific architecture, naming, or testing conventions
• Run a repeatable analysis workflow with supporting scripts or templates

Claude Skills exist in more than one Claude surface:

Surface	How skills are used
Claude.ai / Claude Desktop	Skills are enabled from Claude settings. Anthropic provides built-in skills such as Excel, Word, PowerPoint, and PDF workflows. You can also upload custom skills.
Claude Code	Skills are filesystem folders containing a SKILL.md file. Claude Code discovers them from personal, project, enterprise, and plugin locations.
Claude API / Developer Platform	Skills can be uploaded and managed through the Skills API for programmatic use cases.

This page focuses mainly on Claude Code Skills, because they are easiest to inspect, version, and use in software projects.

---

What Problem Do Skills Solve?

Without a skill, you repeat instructions manually:

When reviewing my code, check for security risks, missing tests, bad error handling,
inconsistent naming, and whether the change matches our architecture rules.
Return findings first, then a short summary.

With a skill, those instructions live in a file. You can ask:

Review my current diff.

Claude can then load the relevant skill and follow the saved workflow.

Skills help with:

Need	How a skill helps
Repetition	Saves instructions you use often
Consistency	Produces outputs in the same structure every time
Team standards	Encodes engineering, writing, review, or business rules
Context management	Loads detailed references only when needed
Automation	Can include scripts and templates for repeatable work
Sharing	Project, organization, or plugin skills can be reused by multiple people

---

Skill vs Prompt vs Project Instruction

Skills are related to prompts and instructions, but they solve a different problem.

Concept	Best for	Example
One-time prompt	A task you only need once	”Summarize this article in five bullets.”
CLAUDE.md / project instructions	Always-on project context	”This repo uses Astro, TypeScript, and Starlight.”
Skill	A reusable workflow loaded only when relevant	”When creating a release note, inspect commits, group changes, and format the output.”
MCP server	Connecting Claude to external tools and data	GitHub, Jira, SQL Server, filesystem tools
Plugin	Bundling skills, agents, hooks, MCP servers, or commands	A team plugin for docs publishing

Use a skill when the instruction is too specific to be always-on but important enough to reuse.

---

How Claude Decides to Use a Skill

In Claude Code, every skill has a SKILL.md file. The important parts are:

1. YAML frontmatter at the top
2. Markdown instructions below the frontmatter
3. Optional supporting files such as templates, examples, references, and scripts

The description field is especially important because Claude uses it to decide when the skill is relevant.

---
name: code-review
description: Review code changes for bugs, test gaps, security risks, and maintainability issues.
---

## Instructions

When reviewing a change:

1. Inspect the diff.
2. Report bugs and risks first.
3. Include file and line references when possible.
4. Keep the summary short.

If the user asks:

Review my current changes.

Claude can infer that the code-review skill should be loaded.

You can also invoke a skill directly with a slash command:

/code-review

---

Where Claude Code Skills Live

Claude Code discovers skills from several locations.

Skill type	Path	Scope
Personal skill	~/.claude/skills/<skill-name>/SKILL.md	Available across your projects
Project skill	.claude/skills/<skill-name>/SKILL.md	Available only in that repository or workspace
Plugin skill	<plugin>/skills/<skill-name>/SKILL.md	Available when the plugin is installed/enabled
Enterprise skill	Managed by organization settings	Available to users in the organization

Example project structure:

my-project/
├── .claude/
│   └── skills/
│       └── release-notes/
│           ├── SKILL.md
│           ├── template.md
│           └── examples/
│               └── good-release-note.md
├── src/
└── package.json

The folder name becomes the slash command:

/release-notes

---

Personal Skills vs Project Skills

Use personal skills for workflows you want everywhere:

~/.claude/skills/summarize-diff/SKILL.md
~/.claude/skills/write-blog-outline/SKILL.md

Use project skills for workflows tied to one codebase:

.claude/skills/astro-docs-page/SKILL.md
.claude/skills/project-release-check/SKILL.md

Project skills are useful when a repository has its own:

• Architecture rules
• Testing commands
• Documentation style
• Release checklist
• Security requirements
• Code review expectations

---

Skill File Anatomy

A practical skill folder can be very small:

my-skill/
└── SKILL.md

More advanced skills can include supporting files:

my-skill/
├── SKILL.md
├── reference.md
├── template.md
├── examples/
│   └── expected-output.md
└── scripts/
    └── validate-output.py

File or folder	Purpose
SKILL.md	Required entrypoint with frontmatter and instructions
reference.md	Longer reference material Claude can read when needed
template.md	Output structure Claude should fill in
examples/	Examples of good output or edge cases
scripts/	Helper scripts Claude can run when the task requires it

Keep SKILL.md focused. Move large reference material into separate files so Claude does not load unnecessary context every time.

---

Important Frontmatter Fields

The top of SKILL.md uses YAML frontmatter:

---
name: release-notes
description: Create release notes from git commits and changed files.
disable-model-invocation: true
allowed-tools: Read Grep Bash
---

Common fields:

Field	What it does
name	Display name for the skill
description	Explains when Claude should use the skill
disable-model-invocation	Prevents Claude from auto-triggering the skill
allowed-tools	Limits which tools the skill may use
arguments	Defines named arguments for slash-command style usage

Most skills should at least include a clear description.

---

When to Disable Automatic Invocation

By default, Claude may load a skill automatically when it seems relevant. That is helpful for safe reference workflows.

For risky workflows, prefer manual invocation:

---
name: deploy-production
description: Deploy the current application to production after all checks pass.
disable-model-invocation: true
---

Use disable-model-invocation: true for skills that can:

• Deploy code
• Send messages
• Publish content
• Modify external systems
• Run expensive jobs
• Touch secrets or credentials
• Delete, overwrite, or migrate data

Then invoke it explicitly:

/deploy-production

---

Example 1 — Code Review Skill

Create:

.claude/skills/code-review/SKILL.md

Add:

---
name: code-review
description: Review code changes for bugs, regressions, security risks, missing tests, and maintainability problems.
---

## Review workflow

1. Inspect the current git diff.
2. Look for behavior changes, broken assumptions, unsafe defaults, and missing tests.
3. Report findings first, ordered by severity.
4. Include file and line references when possible.
5. Keep the summary short and secondary.

## Output format

- Findings
- Open questions
- Test gaps
- Short summary

Use it:

/code-review

Or ask naturally:

Can you review my current changes?

---

Example 2 — Documentation Page Skill

Create:

.claude/skills/docs-page/SKILL.md

Add:

---
name: docs-page
description: Create a technical documentation page for this site using the existing Starlight style.
---

## Instructions

When creating a documentation page:

1. Match the structure and tone of nearby docs.
2. Use frontmatter with title and description.
3. Prefer practical examples over abstract definitions.
4. Add internal links when useful.
5. Run the site build before finishing.

## Style

- Clear headings
- Short paragraphs
- Tables for comparisons
- Code blocks for commands or file examples
- No copied text from external sources

This kind of skill is useful for a site like BankyBluePrints because the same writing and validation rules apply across many pages.

---

Example 3 — Release Notes Skill with Arguments

Create:

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

Add:

---
name: release-notes
description: Generate release notes from a git range.
arguments:
  - from_ref
  - to_ref
---

## Task

Create release notes for changes from `$from_ref` to `$to_ref`.

## Steps

1. Inspect commits in the range.
2. Group changes into Features, Fixes, Docs, and Maintenance.
3. Mention breaking changes clearly.
4. Keep the output customer-readable.

Invoke:

/release-notes v1.2.0 HEAD

---

How to Use Skills in Claude.ai

In Claude.ai, skills are managed through settings rather than project folders.

Typical flow:

1. Enable Code execution and file creation if required by your plan and organization settings.
2. Go to Customize → Skills.
3. Turn built-in skills on or off.
4. Upload custom skills as ZIP packages when needed.
5. For Team or Enterprise plans, owners can provision or share skills across the organization.

Built-in Anthropic skills include workflows for:

• Excel spreadsheets
• Word documents
• PowerPoint presentations
• PDF creation and processing

If you ask Claude to create a PowerPoint or spreadsheet and the relevant capability is enabled, Claude can choose the matching skill automatically.

---

How to Test a Skill

After creating a skill:

1. Start Claude Code in the relevant project.
2. Ask a natural-language request that should trigger the skill.
3. Try direct slash invocation.
4. Check whether Claude loads the right instructions.
5. Inspect the output for missing steps or ambiguity.
6. Tighten the description if Claude loads the skill too often or not often enough.

Example:

What changed in my current branch?

Then:

/code-review

If the skill does not trigger naturally, make the description more concrete.

---

Best Practices

• Make each skill solve one clear problem.
• Use a concrete description; vague descriptions trigger poorly.
• Keep SKILL.md concise and move long references into separate files.
• Add examples for expected output.
• Use disable-model-invocation: true for risky workflows.
• Avoid storing secrets in skill files.
• Version project skills with the repository.
• Review third-party skills before installing or running them.
• Test with realistic requests, not only ideal examples.

---

Common Mistakes

Mistake	Why it causes problems
Vague description	Claude may not know when to load the skill
Huge SKILL.md	Wastes context every time the skill loads
Too many responsibilities	Skill becomes hard to trigger and hard to test
No examples	Claude may guess the output format
Auto-triggering risky actions	Claude may load a deploy/publish/send workflow too early
Copying sensitive internal docs	Skills can expose information to anyone who can read the project

---

Security Notes

Treat skills like executable workflow configuration.

Before using a skill from another person or repository:

• Read the SKILL.md
• Inspect any scripts in scripts/
• Check whether it runs shell commands
• Check what files or network services it touches
• Confirm it does not ask Claude to exfiltrate secrets
• Prefer least-privilege tool permissions

Skills are powerful because they can combine instructions, tools, scripts, and project context. That also means they need the same review discipline as code.

---

Quick Start

Create a simple personal skill:

mkdir -p ~/.claude/skills/summarize-changes

Create:

~/.claude/skills/summarize-changes/SKILL.md

Add:

---
name: summarize-changes
description: Summarize the current git changes and identify risks before committing.
---

## Instructions

Inspect the current diff and return:

1. A short summary of what changed
2. Any risky changes
3. Missing tests or validation
4. A suggested commit message

Use it:

/summarize-changes

---

Useful Links

• Claude Code Skills documentation
• Use Skills in Claude
• How to create Skills for Claude
• Claude Code overview
• Claude AI chat overview