What you’ll make
A working project skill with valid frontmatter, a named command, and test results for direct invocation and automatic selection.
Worked example
Compare an icon sample folder with the listing promise
A creator writes sample-pack-check to verify a digital icon pack. The skill takes a folder and approved listing copy, checks the files against the promised formats, and returns a “Sample pack report” showing present, missing, and extra files. It asks for the listing copy if only a folder was supplied.
The creator tests /sample-pack-check with a folder missing the promised SVG icons. The report names the missing file and leaves the originals in place. A fresh request to “check whether this sample pack matches the listing” should invoke the skill. In a separate session, “rewrite this listing title” should leave it inactive.
Before you start
- Open a repository in your text editor and local Claude Code. Pick one task with a clear input and a repeatable result, and prepare a small example you can safely use in multiple fresh sessions.
- Choose a distinctive skill name such as sample-pack-check. Write a natural request that should trigger it and a similar request for a different task.
Create the project skill directory
At the repository root, create .claude/skills/ and make a folder inside it for your job. Save a blank SKILL.md there. The name of the folder makes it easy to recognize the command later.
I’m checking a digital icon pack, so I name the folder sample-pack-check and create SKILL.md inside it.
The full path I expect to see in my editor is .claude/skills/sample-pack-check/SKILL.md. I check that it ends in .md before I start writing.
Write the YAML header
Put three hyphens on the first line, add name and description, and close the header with three more hyphens. Give the description enough detail for Claude to tell when the skill applies. You can copy the header from the starter worksheet and swap in your own details.
For name I use sample-pack-check. For description I say ‘Compare an icon sample folder with approved listing copy and report missing or extra files.’
That gives me a header that ties the skill to a specific job. I’d expect a request to compare the files with the listing to match. A request to rewrite the listing title has a different job.
Define the workflow and a visible result
Fill in the prompt below with the job, the required inputs, and one example of a good result. Read the returned draft before copying it into SKILL.md. Keep the checked header from step 2 and make sure the instructions say what to do when an input is missing.
I give Claude the sample folder, the approved listing as the second required input, and the heading I want in the answer, ‘Sample pack report.’ I say to ask for the listing if I’ve only supplied a folder.
The draft should tell Claude to compare the promised formats with the actual files and report what’s present, missing, extra, or unverified. I check that it asks for the listing before it tries to guess what the bundle should contain.
Draft the SKILL.md for one repeat job
Use this once you know the job, what goes in, and what a good result looks like.
I want a Claude Code skill for [repeat job]. It should be used when I ask [example request], and should leave [near-miss request] to normal chat. The skill needs [inputs and where to find them]. A good result looks like [sample or output fields]. If an input is missing, it should [ask, stop, or report a gap]. Draft a complete SKILL.md with a YAML name and description. Match the name to the folder [folder name]. Keep the body focused on the workflow: what to inspect, what to produce, what to do if the evidence is incomplete, and what should stay untouched. Include one recognizable output heading and one short example. Put optional reference material in a separate suggested file if it would make the skill easier to read. Show the proposed file path and full contents. Don’t create or install anything until I review it.
Lint and invoke it directly
Check the saved file in the DPV linter’s Skill File mode. Open Claude Code from the repository and run the skill by name with your practice files. Try a complete input first, then leave one required input out. Save the actual responses beside the expected results in your worksheet.
I try /sample-pack-check with a practice folder that has PNG icons and a listing that promises both PNG and SVG. Then I try it with only the folder.
The first run should show PNG under Present and SVG under Missing. The second should ask for the listing. I open the practice folder afterward to confirm the files are still there.
Test automatic selection on fresh requests
Use the prompt below to prepare test requests. Run each in a fresh session so the previous request doesn’t give the answer away. Save the working SKILL.md and your test results together. If you want the skill to run only by command, set disable-model-invocation to true and repeat the direct test.
I try ‘Check whether these files match my sample pack listing’ in one session. In another, I try ‘Rewrite this listing title.’
The first should use the skill and give me the Sample pack report. The second should give me title ideas without starting the file check. If both trigger the skill, I narrow its description and try the two requests again.
Give me three requests to test the skill
Use this after linting the file, then run the requests in separate sessions.
Here’s the SKILL.md: [text or path]. Give me three test requests I can paste into fresh Claude Code sessions: a normal request that should use it, a request that should use it but is missing a required input, and a nearby request that should stay in normal chat. For each test, show the smallest safe example input, what I should see if it works, and what failure would look like. Include the direct slash command for a separate loading check, but keep the three natural-language requests free of the skill name so I can tell whether its description works. Tell me which line to revise if the near miss starts triggering it.
Check your result
- The expected command appears in the Claude Code command list and produces the specified output when called.
- An incomplete example gets a request for the specific missing input.
- Fresh matching and near-miss sessions show the expected behavior for the selected invocation setting.
Troubleshooting
What if the slash command is missing?
Check the project path and filename, including a hidden .txt extension. Confirm the frontmatter delimiters and open a fresh session in the intended repository.
What if direct invocation works but Claude chooses the skill on unrelated requests?
Narrow the description to the concrete request, inputs, and outcome. Retest the match and near miss in separate sessions, or use manual invocation if that fits the workflow.