Do you use skills to standardize your AI workflows?

Skills (slash commands) let you package reusable prompts that standardize how AI agents approach recurring tasks. Instead of retyping the same detailed instructions every time, you define them once and invoke them with a command.

What is a skill?

A skill is a markdown file containing a prompt that gets injected into the AI agent's context when invoked. Think of skills like reusable prompt templates - they guide the agent's behavior for a specific task without needing access to external systems (unlike MCP servers).

---
name: security-review
description: Review code for security, performance, and standards compliance
---

Review the code changes in the current diff for:
- Security vulnerabilities (injection, auth issues, data exposure)
- Performance problems (N+1 queries, unnecessary allocations)
- Adherence to our team's coding standards

For each issue found:
1. Reference the specific file and line number
2. Explain why it's a problem
3. Suggest a concrete fix

✅ Figure: Good example - A SKILL.md file with YAML frontmatter (between --- markers) and markdown instructions

To invoke this skill, type /security-review in Claude Code, @security-review in GitHub Copilot, or simply ask a question that matches the skill's description and the agent will load it automatically.

For connecting to external systems like databases or APIs, use MCP servers instead.

When to use skills

You don't always need to write skills from scratch. Trusted providers like Anthropic publish pre-built skills you can install. For example, Anthropic's official skills repository includes document skills, creative design skills, and development utilities. In Claude Code, you can install them via the plugin system:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Consider creating a skill when:

• You're repeating the same instructions - if you keep typing the same prompt for code reviews, commit messages, or planning tasks, package it as a skill
• You need consistent output - when a task must follow a specific format or checklist every time (e.g. PR descriptions, architecture decision records)
• You're working with internal frameworks - domain specific language or internal tools that aren't well-represented in the AI's training data benefit from explicit guidance
• You're onboarding team members - skills encode tribal knowledge so everyone gets consistent results from day one

❌ Figure: Bad example - Repeating the same detailed review prompt every time is tedious and error-prone

✅ Figure: Good example - A skill encapsulates the review instructions - one command, consistent results every time

Using skills safely

• Always read the full contents of a skill before using it - never blindly trust a skill file, even from a seemingly reputable source
• Avoid skills from third-party marketplaces or untrusted sources - treat installing a skill with the same caution as running an unknown script, we consider skills from sources such as Anthropic and OpenAI to be trusted sources
• Review skill changes in PRs - when a teammate updates a skill, review it like you would review code
• Be cautious of skills that run shell commands - skills that instruct the agent to execute commands or access sensitive files deserve extra scrutiny

Setting up skills

Claude Code

Create a SKILL.md file inside a named directory under .claude/skills/:

.claude/
└── skills/
    ├── security-review/
    │   └── SKILL.md       → invoked with /security-review
    ├── commit/
    │   └── SKILL.md       → invoked with /commit
    └── plan/
        └── SKILL.md       → invoked with /plan

You can also create personal skills at ~/.claude/skills/ that are available across all projects.

GitHub Copilot

Create markdown files in your project's .github/copilot/ directory to define custom agents:

.github/
└── copilot/
    ├── review.md        → invoked with @security-review
    └── plan.md          → invoked with @plan

OpenCode

Create a SKILL.md file inside a named directory under .opencode/skills/ (OpenCode also discovers skills from .claude/skills/):

.opencode/
└── skills/
    ├── security-review/
    │   └── SKILL.md       → invoked as a slash command or loaded by the agent
    └── plan/
        └── SKILL.md

You can also create personal skills at ~/.config/opencode/skills/ that are available across all projects.

Writing effective skills

A good skill is specific about what the agent should do, how it should structure its output, and what it should avoid.

Review the code and give feedback.

❌ Figure: Bad example - Too vague - the agent has no guidance on what to check or how to structure its response

---
name: code-review
description: Review code for security, performance, standards, and test coverage
allowed-tools: Read, Grep, Glob
---

Review the code changes in the current diff for:
- Security vulnerabilities (injection, auth issues, data exposure)
- Performance problems (N+1 queries, unnecessary allocations, missing indexes)
- Adherence to our team's coding standards (which can be found in STANDARDS.md)
- Test coverage gaps

For each issue found:
1. Reference the specific file and line number
2. Explain why it's a problem
3. Suggest a concrete fix

If no issues are found in a category, skip it — do not
list categories with "no issues found."

✅ Figure: Good example - Specific checks, clear output format, and explicit instructions on what to skip

Tips for writing skills:

• One task per skill - a focused skill is easier to maintain and produces more consistent results than one that tries to handle multiple scenarios
• Specify the output format - tell the agent exactly how to structure its response (bullet points, markdown headings, numbered steps, etc.)
• Include constraints - explicitly state what the agent should not do to prevent unwanted behavior
• Use variables where supported - some tools support $ARGUMENTS or similar placeholders so users can pass context when invoking the skill

Frontmatter properties

Skills support optional YAML frontmatter fields that control their behavior:

Skill scope

Where you store a skill determines who can use it:

Personal skills are great for your own preferences and workflows (e.g. your preferred commit message format). Project skills are committed to version control so the whole team benefits. When a personal and project skill share the same name, project-level skills take precedence.

Sharing skills across a team

Project-level skills (committed to the repo) are one of the most effective ways to standardize workflows across a team:

• Commit skills to version control - store them in the project's commands directory so everyone on the team benefits
• Review changes like code - skill updates should go through the same PR review process as any other change
• Reference skills in your README - mention available skills in your project's README so contributors know what's available (e.g. "Run /code-review for a code review" or "Use /deploy to deploy to staging")
• Combine with MCP servers when needed - use skills to define how the agent should work and MCP servers to provide what data it can access

Further reading

• Extend Claude with skills - Claude Code
• Agent Skills - OpenCode
• Custom agents - GitHub Copilot
• Anthropic Skills Repository - pre-built skills for document creation, design, and development
• Do you give your AI agents context with MCP servers and skills? - for guidance on when to use skills vs MCP servers