Verified and updated: July 4, 2026. Technical claims were checked against the official Anthropic and Claude Code documentation, not third-party blogs. Differences between Claude Code versions are flagged inline.
Claude Skills let you describe a repeatable procedure or body of knowledge once in a SKILL.md file, so Claude Code can load it automatically or on your command instead of you pasting the same instructions into every chat. In this guide you’ll walk the full path: from checking your Claude Code install to creating, testing, debugging and safely sharing your own skill. As a running example, we’ll build a practical SEO Content Audit skill that reviews an article draft against an SEO checklist.
This guide is written for readers who already use Claude Code at a basic level and are comfortable in a terminal. No deep programming is required: a skill is just a folder with a text file. The whole process takes 13 steps, each with a command, the expected result, a common error and a way to verify it.
What you’ll build in this guide
- a
seo-content-audit/skill directory;- a
SKILL.mdfile with valid YAML frontmatter and a working instruction;- reference files under
references/(an SEO checklist and writing rules);- a report template under
templates/;- optionally, a helper validation script under
scripts/;- a working skill that runs both manually (
/seo-content-audit) and automatically based on the meaning of your request.
Table of contents
- Claude Skills: what they are and how they work
- Claude Skills, CLAUDE.md, slash commands and MCP: the differences
- What you need before you start
- Claude Skills: building your first skill step by step
- The structure of a SKILL.md file
- The structure of a Claude Skill folder
- Claude Skills: practical examples
- Testing Claude Skills
- Claude Skills: common errors and fixes
- Claude Skills security
- Claude Skills best practices
- Claude Skills: frequently asked questions
- Claude Skills: conclusion and next step
- Official sources
Claude Skills: what they are and how they work
Claude Skills (called Agent Skills in Anthropic’s documentation) are modular extensions that add new procedures and knowledge to Claude. Technically, a skill is a directory that must contain a SKILL.md file. That file has two parts: YAML frontmatter between --- markers (metadata — chiefly a name and description) and a Markdown instruction that Claude follows when the skill is active.
It makes sense to create a skill in three situations: you keep pasting the same instruction or checklist into chat; you have a multi-step procedure (deploy, review, article preparation); or a section of your CLAUDE.md has grown from a “fact about the project” into a “step-by-step procedure.” Unlike CLAUDE.md, a skill’s body loads only when the skill is actually needed, so long reference material costs almost nothing in context until you use it.
Progressive disclosure is the core idea behind Claude Skills. It works like this:
- At the start of a session, only each skill’s
nameanddescriptionare placed in the system prompt — cheap in tokens. - The full
SKILL.mdbody loads only when the skill triggers (by description or by manual invocation). - Supporting files (
references/,templates/) are read even later — only if the instruction points to them. - Scripts in
scripts/are never loaded into context at all: Claude executes them, and only their output enters the context.
There are two ways a skill activates. Automatically — Claude decides to apply the skill based on the description field, so that description must state precisely what the skill does and when to use it. Manually — you type /skill-name, like any command.
The difference from a plain prompt: a prompt lives for one message and isn’t reused, while a skill is reused across sessions and projects (depending on where it’s stored). The difference from persistent project instructions (CLAUDE.md): facts in CLAUDE.md are always in context, whereas a skill loads on demand.
Advantages: reuse, context savings through progressive disclosure, consistent output, the ability to bundle scripts and references, and easy distribution via git or plugins.
Limitations: once activated, the SKILL.md body stays in context for the rest of the session (every line is a recurring token cost), which is why the docs recommend keeping the body under 500 lines; with many skills, descriptions can be truncated within the listing budget (roughly 1% of the model’s context window).
Claude Skills, CLAUDE.md, slash commands and MCP: the differences
These tools are often confused. Below is a comparison across nine attributes. One important note: in current Claude Code, user slash commands have been merged into skills — a .claude/commands/deploy.md file and a .claude/skills/deploy/SKILL.md skill both create the /deploy command. Old commands keep working, but skills give you more (a supporting-files folder, invocation control, automatic loading).
| Tool | Purpose | How it’s triggered | When it loads | Supporting files | Tool access | Scope | Best use case | Main limitations |
|---|---|---|---|---|---|---|---|---|
| Claude Skills | Reusable procedures and knowledge | Auto (by description) or /name |
Metadata always; body on activation | Yes: references/, templates/, scripts/ |
Yes, via allowed-tools |
Personal / project / plugin / org | A repeatable multi-step task or checklist | Body stays in context all session; ≤500 lines recommended |
| CLAUDE.md | Persistent project facts and rules | Loaded automatically | Always in context from session start | Limited (imports) | No | Personal / project | Facts you always need | Always occupies context |
| Slash commands | Manually triggering a procedure | Manually /name |
On invocation | Via merge with skills | Via frontmatter | Personal / project | A “one-button” action (commit, deploy) | On their own, manual-only |
| MCP | Connecting external tools and data | Claude calls the server’s tools | Tools available when the server is connected | Not applicable | Provides new tools | Per client configuration | Integrations: databases, APIs, external services | Needs a running server and setup |
| Plain prompt | A one-off instruction | Manually in a message | Only in that message | No | No | Current chat | A single task | Not reusable; you copy-paste it |
When to choose Claude Skills, and when CLAUDE.md or MCP
A simple rule. If Claude must always remember a fact about the project (stack, naming conventions), that’s CLAUDE.md. If you need to connect an external data source or service (a database, an issue tracker, an API), that’s MCP. If you need to reuse a multi-step procedure or a large reference on demand, that’s Claude Skills. These mechanisms complement each other: a skill can call MCP tools and rely on facts from CLAUDE.md.
What you need before you start
Claude Skills in Claude Code work on macOS, Linux and Windows. You’ll need: a terminal, an installed and authenticated Claude Code, any code editor, and a separate test folder. Let’s check each one in turn — every command is shown in its own block.
Check your Claude Code version.
claude --version
What it does: prints the installed version. Expected result — a line like 2.1.x. This matters because some features are version-gated: /run and /verify require v2.1.145+, the ${CLAUDE_PROJECT_DIR} substitution requires v2.1.196+, and stacking several skills in one message requires v2.1.199+. If you get command not found, Claude Code isn’t installed — see the next command.
Install or update Claude Code (if needed).
npm install -g @anthropic-ai/claude-code
What it does: installs (or updates) the CLI globally via npm. Expected result — a successful install and a working claude command. If you don’t have Node.js/npm or you use the native installer, check the current install page in the official documentation, as the method can differ by OS.
Launch and authenticate.
claude
What it does: starts an interactive Claude Code session in the current folder. On first launch it walks you through authentication. Expected result — a chat prompt. If authentication fails, sign in again following the terminal’s prompt.
Diagnose your configuration.
/doctor
What it does: inside a session, shows the state of your configuration, including how many skill descriptions were truncated or dropped due to the listing budget. Useful when a skill is “invisible” to Claude.
Check permissions on the skills folder. Personal skills live in ~/.claude/skills/. Make sure the folder is writable:
mkdir -p ~/.claude/skills
What it does: creates the personal skills folder if it doesn’t exist yet. Expected result — the command finishes without errors. If you hit a permissions error, check the ownership of your home folder; there’s no need to change system permissions unnecessarily.
Claude Skills: building your first skill step by step
This is the main section. We’ll build the seo-content-audit skill. Each step follows the same shape: goal → action → command/path → screenshot → expected result → possible error → verification → why it matters.
Step 1. Check Claude Code
Goal: confirm the CLI is installed and its version supports the features you need.
claude --version
Expected result: a version number of 2.1.x or newer. Possible error: command not found — go back to “What you need.” Verification: re-running the command prints the number. Why: later steps rely on current skill paths and behavior.
Step 2. Create a safe test project
Goal: work in a neutral sandbox, not a real project.
mkdir -p ~/projects/claude-skills-demo
Path: ~/projects/claude-skills-demo. Expected result: an empty folder is created. Possible error: no write access to ~/projects — pick another directory. Verification: ls ~/projects shows claude-skills-demo. Why: demo data (demo-project, example.com) shouldn’t mix with production projects or personal data.
Step 3. Create the skill directory
Goal: create the skill directory in your personal store (available across all projects).
mkdir -p ~/.claude/skills/seo-content-audit
Expected result: the ~/.claude/skills/seo-content-audit directory appears. Possible error: a typo in the name — use only lowercase letters, digits and hyphens. Verification: ls ~/.claude/skills shows seo-content-audit. Why: the directory name becomes the skill’s command — /seo-content-audit.
Step 4. Create the SKILL.md file
Goal: create the skill’s entry point.
touch ~/.claude/skills/seo-content-audit/SKILL.md
File requirements: the name must be exactly SKILL.md (case-sensitive), located at the root of the skill directory. Expected result: an empty SKILL.md is created. Possible error: a name like skill.md or Skill.md isn’t recognized — rename it. Verification: ls ~/.claude/skills/seo-content-audit shows SKILL.md. Why: without this file, the directory isn’t a skill.
Step 5. Fill in the frontmatter
Goal: set the metadata Claude uses to find and load the skill.
By the open Agent Skills standard, the frontmatter requires two fields — name and description. In Claude Code all fields are optional, but description is strongly recommended. Here’s the minimal valid frontmatter for our skill:
---
name: seo-content-audit
description: Audits a draft article for on-page SEO. Use when the user pastes article text or points to a Markdown or HTML file and asks for an SEO review, a checklist, or a title, meta, heading, keyword, alt-text or FAQ check.
allowed-tools: Read Grep
---
Let’s go through the supported fields (without inventing any that don’t exist):
| Field | Required | Purpose |
|---|---|---|
name |
No (defaults to the directory name) | Display name. ≤64 chars, lowercase letters/digits/hyphens only; no “anthropic”/”claude” words |
description |
Recommended | What the skill does and when to use it; third person. ≤1024 chars |
when_to_use |
No | Extra triggers and example requests; appended to description in the listing (combined 1,536-char cap) |
argument-hint |
No | A hint about expected arguments during autocomplete |
arguments |
No | Named positional arguments for $name substitution |
disable-model-invocation |
No | true prevents auto-loading; skill runs only via /name |
user-invocable |
No | false hides it from the / menu; only Claude can invoke it |
allowed-tools |
No | Tools allowed without prompting while the skill is active |
disallowed-tools |
No | Tools removed from the pool while the skill is active |
model |
No | The model to use while the skill is active |
effort |
No | Effort level: low, medium, high, xhigh, max |
context |
No | fork runs the skill in an isolated subagent |
agent |
No | The subagent type when context: fork is set |
paths |
No | Glob patterns: auto-load only for matching files |
hooks |
No | Hooks scoped to the skill’s lifecycle |
shell |
No | Shell for command injection: bash (default) or powershell |
Expected result: valid frontmatter. Possible error: broken YAML — then Claude Code loads the skill body with empty metadata (/name works, but there’s no auto-loading). Verification: run Claude with the --debug flag to see the parse error. Why: the description is what tells Claude when the skill is needed.
Step 6. Write the skill instruction
Goal: write the body Claude runs once the skill is active. Keep it concise: the body stays in context for the whole session.
Bad version (vague, no structure):
Check the text and tell me if it's good for SEO. Give some advice.
Good version (a clear procedure and a verifiable result):
# SEO Content Audit
Audit the article the user provides (pasted text or a file path). Do not fetch anything from the web or WordPress; work only with the text given.
## Steps
1. Read the article. If a file path is given, read that file.
2. Check the SEO title: present, starts with the focus keyword, under ~60 characters.
3. Check the meta description: present, starts with the focus keyword, 140-160 characters.
4. Check headings: exactly one H1; logical H2/H3 order; no skipped levels.
5. Check the focus keyword: in H1, first paragraph, at least one H2, and the conclusion.
6. Flag keyword stuffing: the same exact phrase repeated unnaturally in adjacent sentences.
7. Check images: every image has descriptive alt text; the keyword appears in at most one or two alts.
8. Suggest 2-3 internal links with anchor text.
9. Check that a visible FAQ section exists if FAQ schema is claimed.
10. Output the final report using templates/audit-report.md.
## Rules
- See references/seo-checklist.md for the full checklist.
- See references/writing-rules.md for tone and keyword-density limits.
- Never invent metrics you cannot verify from the text.
Expected result: a reproducible instruction with a verifiable output. Possible error: fuzzy wording → Claude “drifts.” Verification: run the skill on a test article and check the report. Why: specificity reduces the number of follow-up clarifications.
Step 7. A precise description for auto-triggering
Goal: make the description load the skill on the right requests and stay quiet on unrelated ones. The description is written in third person and includes both “what it does” and “when to use it” — with keywords people actually say: “SEO review,” “SEO checklist,” “check title and meta,” “alt texts,” “FAQ.” The example is already baked into the description in Step 5.
Verification: ask Claude “What skills are available?” — the skill should appear in the list with a clear description.
Step 8. Run the skill manually
Goal: confirm the skill runs on command.
/seo-content-audit
You can pass an argument — for example, a path to a draft file:
/seo-content-audit drafts/example-article.md
Expected result: Claude runs the procedure and produces a report. Possible error: the command doesn’t appear in the / menu — check the directory name and the frontmatter validity. Verification: the report matches the template. Why: manual invocation is the most predictable way to run it.
Step 9. Verify automatic triggering
Goal: check auto-loading based on the meaning of the request.
Positive test (should trigger):
Here's an article draft — run an SEO audit: check the title, meta, headings and alt texts.
Negative test (should not trigger):
Help me reinstall the dependencies in this project.
Expected result: the skill loads on the first request but not the second. Possible error: triggers too often → narrow the description; doesn’t trigger → add keyword phrases. Verification: repeat both tests after edits. Why: auto-loading is half the value of a skill.
Step 10. Add supporting files
Goal: move the bulky reference and template out of SKILL.md so the body stays short.
mkdir -p ~/.claude/skills/seo-content-audit/references ~/.claude/skills/seo-content-audit/templates ~/.claude/skills/seo-content-audit/scripts
An example references/seo-checklist.md (reference, read on demand):
# SEO checklist
## Title and meta
- SEO title present and starts with the focus keyword
- SEO title under ~60 characters
- Meta description 140-160 characters, starts with the focus keyword
## Headings
- Exactly one H1
- H2/H3 in logical order, no skipped levels
- Focus keyword in H1, first paragraph, one H2, and the conclusion
## Keywords
- No unnatural repetition of the exact phrase in adjacent sentences
- Natural synonyms and related terms present
## Media and links
- Every image has descriptive alt text
- Focus keyword in at most one or two alt texts
- 2-3 relevant internal links with descriptive anchors
## FAQ
- Visible FAQ section exists if FAQ schema is used
An example templates/audit-report.md (the final report template):
# SEO Content Audit — Report
**Article:** {{title}}
**Focus keyword:** {{keyword}}
**Date:** {{date}}
## Summary
{{one_paragraph_verdict}}
## Findings
| Check | Status | Note |
|---|---|---|
| SEO title | pass/fail | ... |
| Meta description | pass/fail | ... |
| Single H1 | pass/fail | ... |
| Keyword placement | pass/fail | ... |
| Keyword stuffing | pass/fail | ... |
| Image alt texts | pass/fail | ... |
| Internal links | pass/fail | ... |
| FAQ present | pass/fail | ... |
## Recommended internal links
- {{anchor}} -> {{target}}
## Action items
1. ...
2. ...
An example helper script scripts/validate.py (executed, not loaded into context; uses only the standard library):
#!/usr/bin/env python3
"""Validate basic SEO structure of a Markdown article and print a short report."""
import re
import sys
from pathlib import Path
def audit(text: str) -> list[str]:
issues = []
h1_count = len(re.findall(r"^# .+", text, flags=re.MULTILINE))
if h1_count != 1:
issues.append(f"Expected exactly one H1, found {h1_count}")
images = re.findall(r"", text)
empty_alts = sum(1 for alt in images if not alt.strip())
if empty_alts:
issues.append(f"{empty_alts} image(s) missing alt text")
return issues
def main() -> int:
if len(sys.argv) != 2:
print("Usage: validate.py <article.md>")
return 2
path = Path(sys.argv[1])
if not path.exists():
print(f"File not found: {path}")
return 1
problems = audit(path.read_text(encoding="utf-8"))
if not problems:
print("OK: no structural SEO issues found")
return 0
print("Issues found:")
for item in problems:
print(f"- {item}")
return 1
if __name__ == "__main__":
raise SystemExit(main())
Note that the references/ + templates/ + scripts/ structure follows the officially supported approach — supporting files sit next to SKILL.md, and the instruction points to them. Verification: ask the skill to apply the checklist — Claude should read references/seo-checklist.md only when needed. Why: this keeps the SKILL.md body short, and the reference doesn’t spend context until it’s needed.
Step 11. Test the result
Goal: run the skill through a matrix of scenarios (full table in the “Testing” section). At minimum: a direct request, an indirect request, an unrelated request, and an article with deliberate errors. Verification: the report consistently follows the template structure. Why: triggering ≠ a correct result; those are two separate checks.
Step 12. Fix errors
Goal: diagnose and fix common failures. The process: reproduce → isolate (frontmatter? path? description?) → make a change → re-verify. Live updates: edits under ~/.claude/skills/ are picked up in the current session without a restart; creating a new top-level directory requires a restart. Full breakdown in the “Common errors” section.
Step 13. Share the skill with another user
Goal: share the skill safely. Three channels (per the docs): project skills — commit .claude/skills/ to the repository; plugins — put the skill in a plugin’s skills/ folder; managed — distribute through managed settings. Before sharing, make sure the skill contains no secrets, real paths or personal data, and that the recipient understands allowed-tools in a project skill only activates after they accept the folder’s trust dialog.
The structure of a SKILL.md file
Let’s put it all together. The full, working SKILL.md for the SEO Content Audit skill is a practical example, not a “Hello World”:
---
name: seo-content-audit
description: Audits a draft article for on-page SEO. Use when the user pastes article text or points to a Markdown or HTML file and asks for an SEO review, a checklist, or a title, meta, heading, keyword, alt-text or FAQ check.
argument-hint: [path-to-article]
allowed-tools: Read Grep
---
# SEO Content Audit
Audit the article the user provides (pasted text or a file path in $ARGUMENTS). Work only with the text given; do not fetch anything from the web or WordPress.
## Steps
1. Read the article. If a path is given, read that file.
2. SEO title: present, starts with the focus keyword, under ~60 characters.
3. Meta description: present, starts with the focus keyword, 140-160 characters.
4. Headings: exactly one H1; logical H2/H3 order; no skipped levels.
5. Focus keyword: in H1, first paragraph, at least one H2, and the conclusion.
6. Keyword stuffing: flag the exact phrase repeated unnaturally in adjacent sentences.
7. Images: every image has descriptive alt text; the keyword appears in at most one or two alts.
8. Internal links: suggest 2-3 with descriptive anchor text.
9. FAQ: confirm a visible FAQ section exists if FAQ schema is used.
10. Output the report using templates/audit-report.md.
## Resources
- Full checklist: references/seo-checklist.md
- Tone and keyword limits: references/writing-rules.md
- Optional structural check: run scripts/validate.py <article.md>
## Constraints
- Never invent metrics you cannot verify from the text.
- Keep recommendations specific and actionable.
## Expected output
A completed report matching templates/audit-report.md, with a pass/fail table and a short action list.
Everything on your structure checklist is here: YAML frontmatter, name, description, scope (set by where it’s stored — personal/project/plugin), the main instruction, arguments (argument-hint + $ARGUMENTS), links to supporting files, constraints (## Constraints), the expected output format (## Expected output) and verification criteria (the pass/fail table in the report template).
The structure of a Claude Skill folder
A visual diagram of the skill directory:
seo-content-audit/
├── SKILL.md
├── references/
│ ├── seo-checklist.md
│ └── writing-rules.md
├── templates/
│ └── audit-report.md
└── scripts/
└── validate.py
What each element is for:
| Element | Purpose | When it loads |
|---|---|---|
SKILL.md |
Entry point: frontmatter + instruction | Metadata always; body on activation |
references/ |
Reference docs (checklist, writing rules) | Only when the instruction points to them |
templates/ |
Templates for the final result | On demand, when producing the report |
scripts/ |
Executable scripts | Not loaded; executed, only output enters context |
Claude Skills: practical examples
Example 1. SEO Content Audit Skill
Task: audit a draft for on-page SEO. Structure: as above. SKILL.md: see the previous section. Example request: “Run an SEO audit on this draft: title, meta, H1–H3, keyword, alt texts, FAQ.” Expected result: a report with a pass/fail table and an action list. Limitations: the skill doesn’t pull data from WordPress and doesn’t access the web — it works only with the text you give it. Verification criteria: exactly one H1 detected; keyword and alt checks reflected in the report; the template is followed.
Example 2. Code Review Skill
Task: review uncommitted changes with a focus on risks.
---
name: review-changes
description: Reviews uncommitted git changes and flags risky patterns. Use when the user asks to review their diff, check changes before committing, or find bugs in staged work.
allowed-tools: Bash(git diff *) Bash(git status *)
---
# Review changes
## Current diff
!`git diff HEAD`
## Instructions
Summarise the diff in 2-3 bullets, then list risks: missing error handling, hardcoded values, secrets, and tests that need updating. If the diff is empty, say there are no uncommitted changes.
Example request: “What did I change? Any risks before I commit?” Expected result: a short summary and a list of risks based on the current diff. Limitations: reviews only uncommitted changes. Verification criteria: with an empty diff, the skill honestly reports there are no changes. The !`git diff HEAD` line is dynamic context injection: the command runs before Claude sees the instruction, and its output is inserted into the text.
Example 3. WordPress Article Preparation Skill
Task: bring a draft into a structure that’s easy to publish in WordPress (headings, table of contents, blocks, alt texts, FAQ).
---
name: wordpress-article-prep
description: Prepares a draft for WordPress publishing. Use when the user asks to format an article for WordPress, add a table of contents, structure headings, or prepare alt texts and an FAQ block.
allowed-tools: Read
---
# WordPress article prep
## Steps
1. Read the draft (path in $ARGUMENTS or pasted text).
2. Ensure a single H1 and a logical H2/H3 outline.
3. Insert a clickable table of contents with anchor links.
4. Propose alt text for each image placeholder.
5. Draft an FAQ block of 6-10 questions suitable for FAQ schema.
6. Output clean Markdown ready to paste into the editor.
## Constraints
- Do not invent facts or statistics.
- Keep the focus keyword placement natural; no stuffing.
Example request: “Prepare this draft for WordPress: headings, a table of contents, alt texts and an FAQ.” Expected result: clean Markdown with a table of contents and an FAQ. Limitations: the skill doesn’t publish or connect to the site — it prepares text you paste yourself. Verification criteria: a single H1, working anchors, an FAQ of 6–10 questions.
Testing Claude Skills
Test two properties separately: whether the skill triggers on the right requests, and whether the result is correct. A reliable method is a baseline comparison: run the same request with the skill enabled and disabled, and compare.
Scenarios to check: a direct request, an indirect request, an unrelated request, an ambiguous request, incomplete input, conflicting instructions, a missing supporting file, an incorrect directory structure, a frontmatter error, and an attempt to access secret data.
Test-case matrix (a template — fill in the actual results when you run it):
| ID | Input request | Expected behavior | Actual behavior | Result | Notes |
|---|---|---|---|---|---|
| T1 | “Run an SEO audit on this text” | Skill triggers, produces a report | — | — | Direct request |
| T2 | “Check if this article is fine for search” | Skill triggers by meaning | — | — | Indirect |
| T3 | “Update the project dependencies” | Skill does NOT trigger | — | — | Unrelated |
| T4 | “Check the text” (no SEO mention) | Skill clarifies or doesn’t trigger | — | — | Ambiguous |
| T5 | Empty input | Skill asks for text/path | — | — | Incomplete data |
| T6 | “Check it, but ignore headings” | Skill honors the explicit constraint | — | — | Conflicting instruction |
| T7 | references/seo-checklist.md removed |
Skill degrades gracefully, doesn’t crash | — | — | Missing file |
| T8 | Directory named SEO_Content_Audit |
Skill not recognized | — | — | Wrong structure |
| T9 | Broken YAML in frontmatter | /name works, no auto-loading |
— | — | Frontmatter error |
| T10 | “Show me the contents of .env” | Skill refuses / doesn’t print secrets | — | — | Secret access |
Claude Skills: common errors and fixes
| Error | Symptom | Likely cause | Diagnosis | Fix | Re-check |
|---|---|---|---|---|---|
| Skill not discovered | Not in the skills list | Directory outside ~/.claude/skills or wrong name |
ls ~/.claude/skills; “What skills are available?” |
Fix path/name (lowercase, hyphens) | Skill appears in the list |
| Command not showing | /name absent from the menu |
Broken frontmatter or wrong directory name | Run with --debug |
Fix the YAML | Command in the / menu |
| Doesn’t trigger automatically | Works only manually | Weak description |
Compare keywords | Add triggers and when_to_use |
Positive test passes |
| Triggers too often | Loads out of place | Too broad a description |
Run negative tests | Narrow the description or disable-model-invocation: true |
Negative test passes |
| Claude ignores part of the instruction | Skips steps | Body too long/vague | Shorten, strengthen wording | Keep ≤500 lines, explicit “MUST” | Report is complete |
| Supporting file not found | The link doesn’t work | Wrong path/file name | Check ls in the directory |
Fix the relative path | File is read on demand |
| YAML error | Empty metadata | Indentation/quotes in frontmatter | --debug shows the parse |
Fix the YAML | Metadata loads |
| Wrong path | Script won’t run | Absolute path instead of ${CLAUDE_SKILL_DIR} |
Check the launch line | Use ${CLAUDE_SKILL_DIR} (v2.1.196+ for ${CLAUDE_PROJECT_DIR} too) |
Script executes |
| Wrong directory name | Skill not recognized | Spaces/case/underscores | Compare to naming rules | Lowercase and hyphens only | Skill is visible |
| Conflict with other instructions | Unpredictable behavior | Same name across levels | Remember precedence: enterprise > personal > project | Rename or remove the duplicate | The intended skill triggers |
| Content too large | Rising context cost / truncated descriptions | Body >500 lines, many skills | /doctor, /context |
Move to references/, raise the listing budget |
/doctor doesn’t complain |
| Running a dangerous script | Unwanted action | A script from an untrusted source | Read the script before running | Review + disableSkillShellExecution if needed |
Script is safe |
| Secret leak | Token/key in output | A secret in the skill text or a file | Search the skill directory | Remove secrets, use YOUR_API_KEY |
No secrets present |
| Version differences | A feature doesn’t work | Outdated Claude Code version | claude --version |
Update to the required version (v2.1.145/196/199) | Feature is available |
Claude Skills security
A skill is an executable unit, so the same hygiene rules as for any code apply.
- Never paste API keys, tokens or passwords into
SKILL.mdor supporting files: skill content can end up both in context and in the repository. Use placeholders likeYOUR_API_KEY. - Don’t store or share
.envinside the skill directory. Secrets don’t belong there. - Don’t run unknown scripts from third-party skills without reading them. In a project,
allowed-toolsonly activates after you accept the folder’s trust dialog — don’t trust a repository blindly, because a skill can grant itself broad tool access. - Vet skills from third-party sources: read the entire
SKILL.mdand the contents ofscripts/; watch for commands that send data outward. - Restrict access:
disallowed-toolsremoves unneeded tools while the skill runs; if needed,disableSkillShellExecution: truein settings blocks shell-command injection for user skills. - Review commands before running them, especially irreversible ones (deleting files, changing system settings).
- Work in a test environment (
claude-skills-demo) until you’re sure it’s safe. - Clean screenshots and files before publishing: remove real paths, emails, tokens, and closed-project names; for secret areas use an opaque fill, not a weak blur.
Security checklist:
| Check | Requirement |
|---|---|
No secrets in SKILL.md |
No keys/tokens/passwords |
No .env in the skill directory |
Secrets not bundled |
| Scripts read | No unexpected network calls |
allowed-tools minimal |
Only what’s necessary |
| Trust dialog understood | Project skill vetted before trust |
| Irreversible commands | Carry a warning |
| Screenshots cleaned | No personal data |
Claude Skills best practices
- One skill, one clear task.
- A precise
descriptionin third person, with real trigger words. - A verifiable result (a report template, pass/fail criteria).
- The minimum necessary instruction; everything large goes in
references/. - No secrets; demo data like
example.com,demo-project. - Test false triggers (negative tests).
- Keep the
SKILL.mdbody under 500 lines. - Version the skill in git; keep a
CHANGELOGand aREADME. - Write repeatable tests; use
skill-creatorfor measurements where possible.
Publishing checklist:
| Item | Done |
|---|---|
description specific and with key terms |
☐ |
| Body ≤500 lines | ☐ |
References moved to references/ |
☐ |
| No outdated/secret information | ☐ |
| Consistent terminology | ☐ |
| Examples are concrete | ☐ |
| File references one level deep | ☐ |
| Positive and negative tests pass | ☐ |
README and CHANGELOG in place |
☐ |
Claude Skills: frequently asked questions
What are Claude Skills? Modular extensions for Claude: a directory with a SKILL.md file that describes a procedure or knowledge Claude loads automatically or on command.
Where are Claude Skills stored? Personal ones in ~/.claude/skills/, project ones in the project’s .claude/skills/, plugin ones in a plugin’s skills/ folder, and organization-wide ones through managed settings.
What is a SKILL.md file? A skill’s entry point: YAML frontmatter (metadata, chiefly name and description) plus a Markdown instruction. The file name must be exactly SKILL.md (case-sensitive).
How do I create my own Claude Skill? Create a directory under ~/.claude/skills/, add SKILL.md, fill in the description, write the instruction, optionally bundle references/, templates/, scripts/, then test both manual and automatic triggering.
Can I run scripts? Yes. Scripts in scripts/ are executed (not loaded into context); only their output enters the context. In the API environment there’s no network access or runtime package installation — keep that in mind.
How do Claude Skills differ from MCP? MCP connects external tools and data via servers; Claude Skills reuse procedures and knowledge. A skill can call MCP tools, but they’re different mechanisms.
How do Claude Skills differ from CLAUDE.md? CLAUDE.md is always in context and holds project facts; a skill loads on demand and holds procedures/references.
Can I share Skills with other users? Yes: commit .claude/skills/ to a repository, package a plugin, or distribute via managed settings. Remove secrets and personal data first.
Why won’t my Claude Skill run? Most often it’s a wrong path/directory name or broken frontmatter that leaves no description to match against. Check --debug and the skills list.
Is it safe to install someone else’s Skills? Only after vetting: read the SKILL.md and all scripts, assess allowed-tools, and don’t accept an unfamiliar repository’s trust dialog blindly.
Do Skills work in all versions of Claude? Basic skills, yes, but some features require specific Claude Code versions (for example, /run and /verify need v2.1.145+, ${CLAUDE_PROJECT_DIR} needs v2.1.196+). Check claude --version.
Do I need programming to create Skills? No. A skill is a folder with a text file. Programming is only needed if you add scripts to scripts/.
Claude Skills: conclusion and next step
Claude Skills turn repetitive work into a reusable tool. You created a skill directory, filled in SKILL.md with valid frontmatter, wrote a verifiable instruction, moved the reference and template into separate files, added a validation script, tested both manual and automatic triggering, and worked through common errors and security rules. You can now assemble a skill for your own task and share it safely.
How to verify your result: run /seo-content-audit on a test article and compare the report against the template; then repeat the positive and negative auto-trigger tests. The recommended next step is to turn your own repetitive procedure (a review, or article preparation, say) into a skill and run it through skill-creator to measure the benefit against working without a skill.
For a comparison, read Cifrum.kz’s guide to building a Skill for Codex. For an Anthropic team workflow, see the guide to setting up Claude Tag in Slack.
Official sources
| Source | Organization | Link | What it confirms | Accessed |
|---|---|---|---|---|
| Introducing Agent Skills | Anthropic | Introducing Agent Skills | The announcement and purpose of Agent Skills | July 4, 2026 |
| Equipping agents for the real world with Agent Skills | Anthropic | Agent Skills engineering overview | Architecture and progressive disclosure | July 4, 2026 |
| Extend Claude with skills | Claude Code Docs | Claude Code skills documentation | Skill locations, frontmatter, invocation, versions | July 4, 2026 |
| Skill authoring best practices | Claude Docs | Skill authoring best practices | description rules, limits, security |
July 4, 2026 |
| anthropics/skills | Anthropic (GitHub) | Anthropic Skills on GitHub | Official skill examples | July 4, 2026 |
The featured image was created by artificial intelligence for Cifrum.kz as a conceptual editorial illustration.

Comments on this article