What are Claude skills? How they work, how to install them and how to make one

Claude skills are folders of instructions that teach Claude how to do one specific task, such as building a report your way or following your team's release checklist. Each skill has a SKILL.md file with a name, a short description and the steps; Claude keeps every skill's description in mind and loads the full instructions only when a task matches. Skills work in Claude Code, the Claude apps and the API, and the same format runs in other agents such as Codex.

What a skill looks like

A skill is a directory with one required file and a few optional ones:

weekly-mrr-report/
├── SKILL.md       required: frontmatter and instructions
├── scripts/       optional: code the agent can run
├── references/    optional: docs it reads when needed
└── assets/        optional: templates and sample files

SKILL.md starts with YAML frontmatter between two --- lines, followed by plain Markdown:

---
name: weekly-mrr-report
description: Pulls last week's MRR from Stripe, compares it with the week before and explains the change. Use when the user asks for MRR, revenue this week or the Monday metrics.
---

## Steps

1. List active subscriptions with `stripe subscriptions list --status active --live`.
2. Normalize each item to a monthly amount after discounts, and sum them.
3. Compare with the total from seven days ago and name the three biggest changes.

## Output

Three lines: MRR, the change in dollars and percent, and the main reason.

The rules come from the open Agent Skills standard:

• name: up to 64 characters, lowercase letters, digits and hyphens, matching the folder name.
• description: up to 1,024 characters, saying what the skill does and when to use it. It is the only part Claude reads before deciding, so it carries the trigger words.
• Optional fields include license, compatibility, metadata and allowed-tools. Claude Code adds its own, such as disable-model-invocation: true for a skill you only want to run by hand.

How Claude skills work

Skills load in three stages, which is why you can install dozens without crowding Claude's context:

1. At startup, Claude sees only each skill's name and description, roughly a hundred tokens per skill.
2. When a task matches a description, Claude reads that skill's whole SKILL.md. The standard recommends keeping it under 500 lines.
3. When the instructions point further, to a reference file or a script, Claude opens or runs that file at that moment. A script runs without its code entering the conversation.

This is called progressive disclosure. A long API reference can sit in references/ at no cost until the one task that needs it.

Where Claude skills work

In the Claude apps, skills need code execution. On Free, Pro and Max you turn on "Code execution and file creation" under Settings > Capabilities; on Team and Enterprise an admin enables it for the organization. Skills you enable on claude.ai also load in Claude Code when you sign in with the same account. The sync is one way, and /skills in Claude Code lists them.

Claude Code watches ~/.claude/skills and the project's .claude/skills, so a skill you add or edit there works in the running session without a restart.

How to install Claude skills

• Copy a folder. Put the skill's directory in ~/.claude/skills/ for all your projects, or in the project's .claude/skills/ to share it through git.
• Add a plugin marketplace. Anthropic's own example skills install from inside Claude Code:

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

• Use a one-line installer. Every skill in the skills library on this site has one, for example:

curl -fsSL https://briefkin.dev/skills/weekly-seo-report/install | sh

It saves the SKILL.md to ~/.claude/skills/weekly-seo-report/ and to ~/.agents/skills/ for Codex and other agents.

• Upload in the Claude apps. Zip the skill folder, then go to Customize > Skills, choose +, Create skill and Upload a skill.

Read a skill before you install it. A skill can tell Claude to run scripts and call tools, so treat one from an unknown source like any other code you download.

How to use Claude skills

Mostly you do nothing. Claude reads the descriptions and picks a skill when your request matches, so "what happened to MRR last week?" triggers the skill above. To run one by name in Claude Code, type / and the skill's name, such as /weekly-mrr-report. Claude Code has merged custom slash commands into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy.

For a skill that should never start on its own, such as a deploy or anything that sends email, add disable-model-invocation: true to its frontmatter so it runs only when you call it.

To run a skill on a schedule, start Claude Code from cron with a prompt that names it:

0 9 * * 1 claude -p "Run the weekly-mrr-report skill"

How to create a Claude skill

1. Pick one recurring task you have explained to Claude more than once. Narrow beats broad: "the Friday Jira status report" works better than "project management".
2. Make the folder, for example mkdir -p ~/.claude/skills/friday-status. The folder name becomes the skill's name.
3. Write the description first. Say what the skill does and when to use it, in the words you would actually type: "Use when the user asks for the weekly status, the Friday update or what the team shipped."
4. Write the steps the way you would brief a new colleague: which command or tool, which filters and date range, what the output looks like, and what to do when data is missing.
5. Move long material out. API notes, worked examples and lookup tables go in references/, with one line in SKILL.md saying when to read each.
6. Test both ways. Ask for the task in plain words to check that it triggers, then run /friday-status to check the steps.

Skills compared with MCP, CLAUDE.md and commands

Skills and MCP servers usually work as a pair: the server lets Claude reach Stripe or Jira, and the skill says what to do there and how to present the result. Skills vs MCP goes through when to build which.

Ready-made skills that report on a schedule

The skills library is a set of these for recurring reports: a weekly SEO report from Search Console and GA4, MRR from Stripe, the Friday Jira status report, failed GitHub Actions runs on main. Each one is a single SKILL.md with the API calls spelled out, runs in Claude Code or Codex, and posts its result to your Briefkin board as one card you can check from your phone.