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