{"slug": "how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup", "title": "How to Build a Claude Code Skill That Loads Itself (5-Minute SKILL.md Setup)", "summary": "A developer published a five-minute walkthrough for creating a self-loading Claude Code Skill, a folder containing a single SKILL.md file whose frontmatter description Claude matches against user requests to pull the skill in automatically. The guide covers personal (~/.claude/skills/) versus project-scoped (.claude/skills/) placement, required frontmatter fields like name and description, optional fields such as disable-model-invocation and allowed-tools, and a prompt that delegates folder creation, file writing, and validation via `claude plugin validate` to the agent itself.", "body_md": "Every new session starts the same way: you paste your code review checklist again, re-explain your team’s API conventions again, walk the agent through the release process again. Forget once, and Claude Code falls back to generic habits.\n\nA **Skill** ends the repetition. It’s a folder with one `SKILL.md` file that teaches Claude Code a repeatable task or a piece of standing knowledge. Claude reads the description and pulls the skill in automatically whenever it’s relevant, no manual invocation needed. This guide builds one from scratch in about 5 minutes.\n\nCreate a personal skill that works across every project on your machine:\n\n```\nmkdir -p ~/.claude/skills/api-conventions\n```\n\nThen create `~/.claude/skills/api-conventions/SKILL.md` with a frontmatter block and instructions (see Step 2 below). Claude Code picks it up on its next session start — no restart command needed. Total time: about 5 minutes.\n\nSkip Steps 1-4 below entirely and hand the whole thing to the agent instead — Claude Code can create the folder, write the SKILL.md, and validate it in one session:\n\n```\nYou have file access in this project. Do the following and report back — do not tell me it's done unless step 4 actually confirms it:\n\n1. Ask me what recurring task or piece of knowledge this skill should cover, and whether it should be personal (~/.claude/skills/) or project-scoped (.claude/skills/).\n2. Create the skill folder and a SKILL.md file at the right path.\n3. Write the frontmatter (name, and a description phrased the way I'd naturally ask for this task) plus the instructions body, based on what I told you.\n4. Run `ls .claude/skills/*/SKILL.md` (or the personal-path equivalent) to confirm the file exists, then run `claude plugin validate .claude/skills` to confirm the frontmatter parses cleanly.\n5. If validation fails, do not report success — tell me the exact error and fix it.\n```\n\nThe agent writes the file, then re-checks it exists and parses cleanly before telling you it’s done — instead of you writing the frontmatter by hand.\n\n| Requirement | Why You Need It | Time | \n|---|---|---|\n| Claude Code installed | Skills are a built-in feature — no extra package to add | 0 min | \n| A text editor | To write the SKILL.md file’s frontmatter and instructions | 0 min | \n| A recurring task in mind | Skills are worth building for anything you’d otherwise re-explain repeatedly | ~2 min to define | \n\nPrefer to do it by hand instead of delegating to the agent? Here’s the manual version of the same steps.\n\n~1 min\n\n**Personal skills** live in `~/.claude/skills/` and apply to every project you open. **Project skills** live in `.claude/skills/` at your repo root and are loaded for anyone working in that repo (and its subdirectories, all the way down). Use project scope for team conventions, personal scope for your own habits.\n\nEach skill gets its own folder containing exactly one `SKILL.md`:\n\n```\nmkdir -p .claude/skills/api-conventions\ntouch .claude/skills/api-conventions/SKILL.md\n```\n\n~2 min\n\nThe opening `---` must be the very first line of the file for the frontmatter to parse. `description` is what Claude matches against your requests, so write it the way you’d naturally ask for the task:\n\n```\n---\nname: api-conventions\ndescription: REST API design conventions for our services\n---\n# API Conventions\n- Use kebab-case for URL paths\n- Use camelCase for JSON properties\n- Always include pagination for list endpoints\n- Version APIs in the URL path (/v1/, /v2/)\n```\n\nOptional frontmatter fields: `disable-model-invocation: true` makes it callable only via `/api-conventions`, never triggered automatically; `allowed-tools` restricts which tools Claude can use while the skill is active.\n\nStart (or restart) a Claude Code session in the project, then ask a question that matches the description naturally — Claude should pull the skill in on its own. To force it regardless of description matching, call it directly:\n\n```\n/api-conventions\n```\n\nA Skill loads itself when the task matches, so you stop repeating the same instructions.\n\n| Piece | What It Does | \n|---|---|\n| `name` | Sets the skill’s invocation name; without it, Claude falls back to the folder name | \n| `description` | What Claude matches against your requests to decide when to auto-trigger the skill | \n| `disable-model-invocation` | Turns off automatic triggering, leaving only manual `/name` invocation | \n| `allowed-tools` | Limits which tools are available while this skill’s instructions are active | \n| Skill body (below frontmatter) | The actual instructions Claude follows once the skill is loaded | \n\nConfirm the file exists and the frontmatter parses cleanly:\n\n$ ls .claude/skills/*/SKILL.md\n\n.claude/skills/api-conventions/SKILL.md  \n\n$ claude plugin validate .claude/skills\n\n✔ api-conventions: valid\n\nRun the same two commands yourself:\n\n```\nls .claude/skills/*/SKILL.md\nls ~/.claude/skills/*/SKILL.md\nclaude plugin validate .claude/skills\n```\n\nInside a Claude Code session, ask **“What skills are available?”** — your skill should appear in the list. If the frontmatter has a YAML syntax error, the skill still loads but with no description to match against, so it’ll only work via manual `/name` invocation.\n\n`---` isn’t on line 1.`SKILL.md` per folder.`/name` working means the description-matching works too.\nPersonal and project skills are picked up on the next session start. Skills in directories added mid-session (via `/add-dir`) also load at that point without a full restart.\n\nYes — that’s what the copy-paste prompt above is for. Claude Code can create the folder, write the SKILL.md, and run the validator itself instead of you writing the frontmatter by hand.\n\nYes, unless `allowed-tools` restricts it — by default a skill’s instructions run with the same tool access as the rest of the session.\n\nA skill can trigger automatically based on its description matching your request. A plain slash command only runs when you type it explicitly — skills with `disable-model-invocation: true` behave like slash commands.\n\nYes — put it under `.claude/skills/` in the repo and commit it. Anyone who clones the repo gets it automatically.\n\n*Originally published at [quickpromptco.com](https://quickpromptco.com/create-install-claude-code-skill-setup-guide/), where the guide is kept up to date.*", "url": "https://wpnews.pro/news/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup", "canonical_source": "https://dev.to/juholee/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skillmd-setup-2jjb", "published_at": "2026-09-30 01:00:28+00:00", "updated_at": "2026-09-30 01:16:52.517286+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Claude Code", "Anthropic"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup", "markdown": "https://wpnews.pro/news/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup.md", "text": "https://wpnews.pro/news/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup.txt", "jsonld": "https://wpnews.pro/news/how-to-build-a-claude-code-skill-that-loads-itself-5-minute-skill-md-setup.jsonld"}}