Do you use skills to standardize 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.

Figure: ... I know Kung Fu 🥋

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

The best way to discover and install skills is skills.sh - Vercel's open agent skills ecosystem. It's a registry of community and official skills plus a CLI that installs a skill into the right location for whichever agent you use (Claude Code, GitHub Copilot, Cursor, Codex, and 70+ others) - no per-agent setup required:

npx skills add anthropics/skills --skill frontend-design

If you're using Claude Code only, you can alternatively install via the plugin system:

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

Consider creating a skill when you are:

• Repeating the same instructions - If you keep typing the same prompt for code reviews, commit messages, or planning tasks, package it as a skill
• Needing consistent output - When a task must follow a specific format or checklist every time (e.g. PR descriptions, architecture decision records)
• 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
• 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 company skills

You should create a repository which acts as the source of truth for all general-purpose skills. Doing so allows developers to store and share skills safely and securely. Skills that are updated/introduced should go through a review process to ensure that no safety issues are being introduced.

Project-specific skills should be stored within their project repositories.

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

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

Publishing skills

To share skills beyond your team, publish them to skills.sh. There's no submission process - push a public GitHub repository containing your SKILL.md files and anyone can install them with one command, regardless of which agent they use:

npx skills add your-org/your-skills-repo

This beats maintaining separate install instructions for Claude Code, Copilot, Cursor, and every other agent - the skills CLI puts the skill in the right place for each one.

Setting up skills

If you installed a skill via npx skills add, the CLI already placed it correctly for your agent - the locations below are for writing your own skills manually.

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

Say when the skill should trigger

The description is not documentation. It is the text the agent reads to decide whether to load the skill at all. A skill that is installed but never fires is wasted, and a skill that fires on the wrong request is worse.

Matching is semantic, not a string comparison, so the agent will recognise paraphrases. It still needs to know the intent. Write the description in three parts: what the skill does, examples of what a user says when they want it, and any scope guard. Then test it with a few different phrasings and adjust.

description: Helps with sprint reviews

❌ Figure: Bad example - Too broad to separate this skill from a retro summary, a sprint report, or a planning session

description: Prepare draft emails for a Sprint Review, Retro, and Planning meeting.
  Trigger when the user says "prepare sprint review", "draft sprint emails",
  "sprint review prep", or asks to get ready for the sprint ceremony.
  Accepts an optional sprint number and auto-detects the board from the repo.
  Drafts only - never sends email.

✅ Figure: Good example - What it does, example phrases, what it accepts, and what it will never do

Some skills should only run when a person asks for them by name, for example anything that pushes, sends, bills, or deletes. Say so in the description, and in Claude Code set disable-model-invocation: true so the agent cannot load the skill on its own. Other tools ignore that field. OpenCode, for example, reads only its own frontmatter fields, so there the guard has to come from the agent's tool permissions rather than the skill file.

Keep SKILL.md short and load the rest on demand

A skill that runs to 600 lines is loaded into the context window in full every time it triggers. Keep the SKILL.md to the workflow, roughly 100 lines, and put the long material beside it:

skills/
└── timesheets/
    ├── SKILL.md              → the workflow, read every time
    ├── references/
    │   ├── source-gathering.md   → read only when the step needs it
    │   └── gotchas.md
    └── scripts/
        └── scan_activity.py      → run, not read

Tell the agent in SKILL.md which reference to open at which step. The agent pays for the detail only when it needs it.

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

Here are some common properties to include, you can view the full spec here: https://agentskills.io/specification#frontmatter-required.

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.

Further reading

• skills.sh - The Open Agent Skills Ecosystem - Discover, install, and publish skills across 70+ agents
• Specification - Agent Skills
• 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