Skip to content

Claude Skills — Reusable Workflows for Claude

Claude Skills — Reusable Workflows for Claude

Section titled “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.


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

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.


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

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

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

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.


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.


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

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?

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

Section titled “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

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.


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.


  • 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.

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

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.


Create a simple personal skill:

Terminal window
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