Artificial Intelligence

Claude Skills: How to Build Your Own Skill From Scratch

Claude Skills — a hands-on guide to building your own skill in Claude Code: SKILL.md structure, frontmatter, testing, common errors and security.

Author Aliya
28 min read

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.md file 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 (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:

  1. At the start of a session, only each skill’s name and description are placed in the system prompt — cheap in tokens.
  2. The full SKILL.md body loads only when the skill triggers (by description or by manual invocation).
  3. Supporting files (references/, templates/) are read even later — only if the instruction points to them.
  4. 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.

Related:  Historic Milestone: Bots Surpass Humans in Web Traffic for the First Time

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.

Related:  OPEN WI-FI: WHEN FREE CHEESE TURNS INTO A TRAP FOR YOUR DATA

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
Related:  14 FATAL ERRORS DURING INSTALLATION OF THE SERVER ROOM (HARDWARE)

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.md or supporting files: skill content can end up both in context and in the repository. Use placeholders like YOUR_API_KEY.
  • Don’t store or share .env inside the skill directory. Secrets don’t belong there.
  • Don’t run unknown scripts from third-party skills without reading them. In a project, allowed-tools only 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.md and the contents of scripts/; watch for commands that send data outward.
  • Restrict access: disallowed-tools removes unneeded tools while the skill runs; if needed, disableSkillShellExecution: true in 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 description in 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.md body under 500 lines.
  • Version the skill in git; keep a CHANGELOG and a README.
  • Write repeatable tests; use skill-creator for 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

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top