Zilmac Blog
← Back to Tech Practice

How to Create Custom Skills for Claude Code: A Complete Tutorial from Writing SKILL.md, Directory Setup, and Actual Invocation

AIDevelopment ·~13 min read

A Skill is ready only when Claude Code can find its SKILL.md, the file is in a supported Skills directory, and a real task confirms that the instructions are followed. Start by choosing a project or personal location, then verify both explicit invocation and automatic matching against the current Claude Code Skills documentation, because paths and invocation behavior can change.

This guide is for developers who want to turn recurring Claude Code tasks into reusable instructions, teams deciding whether a workflow belongs to one project or an individual, and technical staff validating Skills as part of an AI Agent workflow.

Creating custom Skills for Claude Code starts with three checks

>

Do not judge a Skill by whether its file exists. Check three things separately:

  • File: a SKILL.md contains valid frontmatter and actionable instructions.
  • Location: the containing Skill directory is under a supported project or personal Skills path.
  • Behavior: Claude Code invokes it in a test and the result reflects the instructions.

The first two checks establish that the Skill is configured. The third establishes that it works for the task at hand. Passing one does not prove the others: a perfectly written file in the wrong directory will not be discovered, and a recognized Skill can still have vague instructions that produce inconsistent results.

Treat “recognized” and “working” as different test results. Explicit invocation is a good first test because it avoids guessing whether the model will infer that a prompt matches the Skill. Automatic matching is a separate behavior to test after the direct invocation succeeds.

The official Skills reference documents the current locations, frontmatter, and invocation options. Use it as the source of truth before copying a directory layout from an older tutorial or a teammate’s setup.

Choose a project or personal directory

>

Claude Code Skills can be scoped to a project or to a user. Pick the scope based on who should reuse the workflow, not on which path is easiest to remember.

Location Best fit Scope rating What to verify
.claude/skills/<skill-name>/SKILL.md A project workflow that should travel with that project Strong for shared project work The path is inside the project’s .claude/skills/ directory
~/.claude/skills/<skill-name>/SKILL.md A personal workflow useful across multiple projects Strong for individual reuse The file is under the current user’s Claude Code configuration
A Skill distributed as part of a plugin A workflow delivered through a plugin setup Conditional Follow the plugin’s documented structure and installation process

These paths and scope descriptions reflect the current Claude Code Skills documentation. The table’s ratings are editorial guidance, not a guarantee that a particular installation will load a Skill. Check the current documentation if an existing setup uses another location or if the Claude Code version is managed by a team.

A project-level Skill is easier to review alongside the codebase. That makes it a natural choice for repository-specific conventions, such as how to inspect a migration or prepare a pull request. A personal Skill suits a workflow that should remain available when you move between unrelated projects. If collaborators need the same instructions, relying on a personal directory makes the configuration harder to share and audit.

For a minimal project setup, create a directory for the Skill and add the instruction file:

your-project/
└── .claude/
    └── skills/
        └── project-review/
            └── SKILL.md

The directory name becomes part of the Skill’s identity, so choose a descriptive, stable name such as project-review rather than a generic label such as helper. Keep the SKILL.md file directly inside that Skill’s directory unless the current documentation specifies another structure for an advanced setup. Supporting files can be useful for longer workflows, but the entry point should remain easy to find.

A path that looks correct in an editor is not enough. Confirm the working directory Claude Code is using, then compare the actual filesystem path with the documented project or personal location.

Write SKILL.md around a task and a boundary

>

A good SKILL.md tells Claude Code what the workflow does, when it applies, and how to perform it. Keep its purpose narrow enough that a developer can recognize when the Skill is relevant. A Skill called project-review should not mix code review, release planning, incident response, and unrelated repository maintenance into one set of instructions.

The official format uses YAML frontmatter followed by the Skill’s instruction body. At minimum, provide name and description in the frontmatter; consult the current Claude Code Skills documentation for the current field definitions and restrictions. The documented limits include a maximum of 64 characters for a Skill name and 1,024 characters for its description. The Agent Skills format specification provides additional format context, but Claude Code’s documentation should govern Claude Code-specific behavior.

A small demonstration file could look like this:

---
name: project-review
description: Review a proposed change for correctness, missing tests, and project-specific risks. Use when asked to inspect a diff or assess a change before merging.
---

# Project review

1. Inspect the supplied diff and identify the files that changed.
2. Read the nearby code and relevant project instructions before judging the change.
3. Report only issues supported by the diff or repository context.
4. Group findings by severity and cite the affected file and location.
5. If no actionable issue is found, state that clearly and list any checks that were not performed.

Do not modify files unless the user explicitly asks for changes.
Do not claim that tests passed unless you ran them and observed the result.

This is a demonstration, not a promise that every prompt will produce identical results. Its description gives Claude Code a recognizable task and states when the Skill applies. The body defines a sequence, limits unsupported claims, and sets a clear boundary on file changes.

Avoid writing only a label such as “review code.” That gives little guidance about when the Skill should run or what a useful result looks like. Also avoid vague instructions such as “be thorough” without saying what to inspect or report. Prefer observable requirements: identify the changed files, cite evidence for each finding, and disclose checks that were not run.

For more complex Skills, separate reusable reference material from the main instructions rather than making the entry file a long handbook. The official Skill creator example is useful for seeing a fuller example of Skill-writing guidance. Treat it as an example to study, not as a substitute for checking Claude Code’s current supported fields.

Configure the Skill and verify the loading conditions

>

Before testing, check the directory, filename, YAML, and scope as separate items. Use the official Skills reference to confirm current requirements, especially if a Skill was copied from an older repository. If the problem seems related to project-level configuration rather than the Skill itself, compare it with the Claude Code settings reference.

Check Passing condition Common failure
Supported location The Skill is under the project or personal directory documented for Claude Code The directory is nested under the wrong project path or stored elsewhere
Entry filename The entry file is named SKILL.md A different filename or capitalization is used
Skill folder The file is inside a directory with a clear Skill name The file is placed directly in skills/ without its own directory
Frontmatter YAML is valid and includes the documented required fields Broken delimiters, malformed YAML, or missing description
Description The description states the task and the conditions for using it The description is too broad or does not match the task users will request
Scope The project or personal location matches the intended audience A personal Skill is expected to be available to everyone on a team

A practical validation sequence is:

  • Confirm the working directory. Check that the project root you have open is the repository containing .claude/skills/, if this is a project Skill.
  • Inspect the full path. Confirm that the folder and file are nested as intended; do not rely on a search result with a matching filename elsewhere.
  • Read the frontmatter as YAML. Check the opening and closing delimiters, spelling, indentation, and required fields against the current reference.
  • Check the description against real prompts. It should describe the tasks that should activate the Skill, not merely repeat the Skill name.
  • Retest after editing. If discovery still looks stale, start a fresh Claude Code session and test again. This is a troubleshooting step, not a claim that every Skill edit always requires a restart.

Separate Skill format errors from permissions and settings issues. For example, if the file is present but Claude Code does not behave as expected, check whether the project’s configuration changes the available behavior. Use the settings reference to verify setting names rather than inventing or copying an unsupported configuration key. Do not move a Skill into a different scope until you have confirmed that the current path is wrong; changing the scope can hide the original problem.

Invoke the Skill and inspect what it does

>

Test explicit invocation before automatic matching. With the example above, try:

/project-review Review the changes in the current diff. Do not edit files.

The slash-command name is based on the Skill name. The current Claude Code Skills documentation explains supported invocation and how a Skill’s configuration affects whether it can be invoked by the user or by the model. If you add optional frontmatter that changes invocation behavior, verify the current field definitions before relying on it.

Use a test task with a visible result. For project-review, supply a small diff or ask Claude Code to inspect a real change, then check whether it identifies changed files, supports findings with evidence, distinguishes unperformed checks, and respects the instruction not to edit. Do not count a response that merely says “I used the Skill” as proof that the output followed the workflow.

Once explicit invocation works, test automatic matching separately. Describe a task that fits the Skill’s description without typing the slash command. For example, ask for a review of a proposed change and request evidence-based findings. If the Skill’s instructions are followed, the test suggests that the description and request align. It does not prove that every loosely related prompt will select the Skill; automatic matching depends on how clearly the request fits the Skill’s purpose.

Use this decision path:

  • If the Skill is project-specific and collaborators should use it, choose the project directory; otherwise, use the personal directory.
  • If explicit invocation fails, return to the path, filename, and frontmatter checks before editing the instructions.
  • If explicit invocation works but automatic matching does not, revise the description to state the task and activation conditions more clearly, then retest with a direct request.
  • If the Skill activates but the output drifts, tighten the steps, boundaries, and completion criteria rather than changing the directory.
  • If the workflow must not be invoked automatically, check the current documentation for the supported invocation controls before adding frontmatter fields.

The official command reference is not the primary source for Skills behavior, so use the Skills reference for Skill-specific invocation rules. The useful distinction is operational: commands and Skills may have related user-facing invocation patterns, but that does not mean their file layouts or configuration rules are interchangeable.

Close the loop when a Skill is missing or inconsistent

>

When a Skill does not appear, begin with discovery rather than rewriting the whole file. Confirm that Claude Code is running in the intended project, that the directory is under a documented location, and that the entry file is exactly SKILL.md. Then inspect the frontmatter. A malformed YAML block or a description that does not identify a useful task can prevent the Skill from being recognized or selected as expected.

When it appears but does not trigger automatically, compare the actual request with the description. A description that says “helps with code” is unlikely to distinguish a review task from implementation, debugging, or documentation work. State the intended task in terms a user might actually request, and include clear conditions that separate it from nearby tasks.

When it triggers but produces the wrong kind of result, add missing process details to the body. Specify what inputs to inspect, what output format to use, what evidence is required, and what actions are out of scope. Keep the instructions short enough to follow, and avoid conditions that contradict one another.

After any change, repeat the same test task and compare the new output against the same observable requirements. That creates a useful troubleshooting loop: change one likely cause, rerun the test, and record whether the failure moved. If the behavior still differs from the documentation, check the current Claude Code version and official guidance before assuming an old configuration is still supported. The official memory documentation also helps distinguish project instructions and memory from a Skill: they serve related but different roles, so replacing one with the other may not fix discovery or invocation.

FAQ: Claude Code Skills

>

What belongs in SKILL.md?
Write the task, when it applies, the steps to follow, and clear boundaries. Include a completion check that lets you inspect the output. Keep the frontmatter valid and use the current documented fields.

How should the directory be configured?
Use the project Skills directory for a project workflow and the personal Skills directory for an individual workflow across projects. Confirm the paths in the current official documentation.

How does Claude Code recognize and invoke a Skill?
Test its slash-command name explicitly first. Then test automatic matching with a request that clearly fits the description. Check the resulting work, not just whether the Skill was mentioned.

What should you do if the Skill does not trigger?
Verify the working directory, supported path, folder structure, exact filename, YAML, and description. If explicit invocation works but automatic matching does not, refine the description and repeat the same test.

For a real validation, choose one repetitive task, write its SKILL.md, and run the same observable test after each change. If that workflow also depends on a remote Mac development environment, compare the limits of the current setup—such as environment drift, shared-machine scheduling, or no suitable Mac available for testing—with the environment and delivery details described on Zilmac’s Mac rental page. That option is relevant when you need a temporary remote environment; it is not a substitute for a Skill, and a local setup remains simpler when it already meets the workflow’s needs. Review Zilmac’s service information before deciding whether it fits the way the team works.

FAQ

What should I put in a Claude Code SKILL.md file?

Write a short description of the task, when the Skill should and should not apply, and the steps Claude Code should follow. Put the name and description in YAML frontmatter, then use the body for the actual workflow. Add concrete constraints and an observable completion check so you can tell whether the Skill followed its instructions.

Where should I configure Claude Code Skills?

Use `.claude/skills//SKILL.md` when the workflow belongs to one project and should be shared with its collaborators. Use `~/.claude/skills//SKILL.md` for a personal Skill intended to work across projects. Check the current official Skills documentation before relying on paths or loading behavior, especially if your Claude Code version is older.

How can I tell whether Claude Code recognized and invoked a custom Skill?

Start with an explicit invocation using the Skill’s slash-command name, then give it a small task with an output you can inspect. Compare the result with the steps and constraints in SKILL.md. To test automatic matching, describe a task that fits the Skill’s description without naming the Skill; do not treat a single match as proof that every similar request will trigger it.

Why is my Claude Code Skill not triggering?

Check that the file is named `SKILL.md`, sits inside a Skill-named directory under a supported location, and has valid YAML frontmatter with a useful description. Then test the slash command directly. If explicit invocation works but automatic matching does not, revise the description to state the tasks and conditions that should activate the Skill, and retest with a clear matching request.

Run Your macOS Workflows on a Dedicated Cloud Mac

Rent a bare-metal M4 Mac mini with full macOS for builds, automation, and development.

Connect over SSH or VNC and keep your local computer free for other work. — View Plan Options

Limited Offer

Zilmac

Rent a bare-metal M4 Mac mini with full macOS for builds, automation, and development.

Back to Home
Limited Offer View Plans