A Pre-Launch Test Checklist for Claude Code Skills

You casually ask in the terminal, "what does this function do?" Claude responds with a full review report, complete with severity ratings and three "suggested fixes." You only wanted to understand one function.

Most likely, your code review skill's description is too broad, and an ordinary question got pulled into the review workflow. The reverse happens just as often: someone asks "can this be merged?", which is really a question about behavior risk and missing tests, and the skill never fires because its description only says "type /review."

Once a skill is written, being callable is only step one. Before sharing it, confirm a few more things:

• Relevant requests turn it on, and unrelated requests leave it quiet.
• Once on, it reads materials, makes judgments, and returns results in the agreed order.
• At important decisions you haven't approved yet, it stops and waits.
• When information is missing, it says what's missing instead of filling the gap itself.

One successful call won't show you any of that. Write the workflow as executable steps that leave intermediate outputs, put approval points at decisions not yet authorized, and test with paired sets of related and unrelated requests. Then check the call log and the files it actually read to confirm it followed the method.

01 Write the workflow as executable steps

A skill body is an operating manual. It should make the order, approval points, and output clear. A clear workflow usually covers:

• What input the user must provide.
• Which files must be read before continuing.
• Which steps can run automatically.
• Which steps need user approval.
• How intermediate outputs are saved.
• How to tell the task is done.
• What the output format is.
• What to do when information is missing.

A blog drafting skill, for example, can be broken down like this:

## User input

The user should provide:

- An idea or topic
- Available sources
- Target readers
- Tone or style
- Target length

## Workflow

1. Create the article folder and a resources subfolder.
2. Collect sources and save summaries.
3. Extract the topic, angle, key points, and information gaps.
4. Ask the user clarifying questions.
5. Draft an outline and wait for approval.
6. Save the approved outline.
7. Write the draft from the outline.
8. Save the draft version.
9. Show the draft and wait for feedback.
10. Revise based on feedback or finalize.

02 Intermediate outputs show where things went off track

Anyone who has produced complex content knows the feeling: you get a final draft with scattered, unclear arguments, and with nothing but that draft, it's hard to reconstruct where it went wrong. Were the sources off, was the outline flawed, or did the draft drift away from the structure?

If the skill requires saving each stage's output, the diagnosis gets clear. If the outline is solid, the problem is a draft that didn't follow it. If the outline is already fragmented, the earlier extraction went wrong. Work backward through the intermediate outputs and the failing stage is much easier to find.

Version management for a writing skill can look like this:

blog-posts/
└── YYYY-MM-DD-topic-name/
    ├── resources/
    │   ├── source-1-name.md
    │   └── source-2-name.md
    ├── OUTLINE.md
    ├── draft-v0.1.md
    ├── draft-v0.2.md
    └── final.md

When the user asks to revise an existing draft, the skill should read the current draft first and go straight into revision, skipping the source collection and outline stages.

03 Put approval points at decisions not yet authorized

Approval points belong at important decisions that haven't been authorized yet, such as finalizing an outline or writing to disk. Actions already agreed on, with clear context, can proceed within that authorization. If the user has stated the goal, scope, and action, continue within that scope. Check these categories carefully:

• Overwriting important files outside the request, or writes whose impact is unclear.
• Publishing, deploying, pushing, committing, and changing live resources.
• Major choices about the user's material, such as an article's position or a brand or product message.
• Large deletions, renames, or migrations.

Fill in the scope when it's unclear; confirm again when the work goes beyond the original request. You can write the waiting points into the skill:

## Approval points

- After drafting the outline, wait for the user's approval or edits.
- Before committing or pushing, state which files will be committed.
- Production deployments may only be triggered explicitly by the user.

For example, if the user has supplied sources, a position, and a structure and asked for a finished beginner's blog post, the writing scope is clear and the skill can produce the draft. If you agreed to review an outline first, make the outline a reviewable result and wait at that point.

If the user then asks to publish, that's a new action. Confirm the channel and scope that aren't settled yet, and continue with what's already approved. Find the missing decision first, then place the approval point, and the flow feels natural.

Deployments, database migrations, bulk deletions, and production config changes can also keep a manual entry with disable-model-invocation: true, which stops Claude from starting the skill on its own:

---
name: production-deploy
description: Run pre-deployment checks and the release process. Use only when the user explicitly asks to deploy, release, or go live.
disable-model-invocation: true
---

Who starts it and what it does once started are still separate questions. The method still has to cover the target environment, scope, and recovery from failure. To keep the start switch, approval shortcut, and real block apart, see why a "read-only" Claude Code command still edits.

Skills can also take input through $ARGUMENTS, $0, and $1, and inject current project state with !`command`. Keep two limits on dynamic context: inject only what this task needs so the context doesn't bloat, and remember dynamic commands run before the body, so keep them to short read-only queries and put writes that need approval in the body's steps.

04 description decides when the skill turns on

description should name the trigger scenarios, task types, and boundaries. Too broad and it fires constantly; too narrow and it misses real requests.

A weak description:

description: Helps with writing.

A usable one:

description: Draft blog posts from the topic, sources, and target readers the user provides. Use when the user asks for a blog post, an article outline, a long-form draft based on sources, or a revision of an existing draft.

Once written, try a few phrasings. "Can this be merged?" is also asking about behavior risk and missing tests; a description that only says "type /review" or "review the current branch diff" may miss it. On the other side, "helps with writing" sweeps in plenty of unrelated requests.

Look at what the task does, then choose the words that describe it. Only by comparing similar requests in different wording, plus unrelated requests, can you tell whether a description has the right range. The Claude Code skills documentation also notes that each skill's listing text has a length cap and long descriptions get cut, so put the key use case first.

05 Test triggering and execution with paired requests

Testing a skill means more than "can it be called." Check trigger boundaries, step order, material loading, and high-risk approval points:

Use this table for positive and boundary tests before sharing. Positive tests prove it works; boundary tests prove it stays out of unrelated work. Two small tests:

Test 1: positive trigger
Review the current diff, focusing on permission checks and test gaps.

Test 2: boundary
Explain what this function does.

The first should enter the review; the second usually only needs an explanation. If disable-model-invocation: true is set, start the first one manually with /code-review.

Split the observation in two:

An answer with "Findings" and "Impact" headings may just be the model's habitual format. Check the call log and the files it read to confirm the skill was active and that it read references/security-checklist.md.

Back to that uninvited review report. A question about what a function does landed in the review workflow, and only two checks together, "which files did it actually read" and "does it misfire in boundary cases," tell you whether the skill runs the way you designed it.

06 Check external scripts before granting execute permission

If an installed skill runs scripts directly, review the actual files before granting execute permission. External scripts may touch the network, files, or credentials. Check each one:

• Network: does it send requests, and where does the data go?
• Files: does it write files or change config, and is that inside the task's scope?
• Credentials: does it read sensitive variables like $TOKEN or $KEY, and how does it use them?
• Dependencies: which local commands does it need, and how does it fail when they're missing?

Then add execute permission one reviewed script at a time:

chmod +x ~/.claude/skills/refactor-helper/scripts/run-tests.sh

Running chmod -R +x on a whole folder to save time trusts every script you haven't read yet.

07 Four common problems

If the skill doesn't trigger, check the discoverable location, directory name, SKILL.md, and YAML first, then whether the name and description are clear, whether the current task matches, and whether a better-matching skill exists.

If the skill triggers too often, adjust it:

• Tighten the description.
• Add conditions for when it applies.
• Name the task type clearly.
• Use fewer broad words like "help," "optimize," or "handle."
• Make high-risk skills user-triggered only.

If Claude can't see the supporting files, check that the paths are correct, the files are inside the skill directory, scripts have execute permission, file names referenced in SKILL.md match, and whether the session needs to reload.

If execution drifts from what you expected, the usual causes are:

• SKILL.md states a goal but no steps.
• The output format is too vague.
• There are too many references with no reading order.
• Approval points aren't spelled out.
• Several unrelated capabilities are packed into one skill.

Finally, walk through one real call: are the name and description clear, does it solve one problem, do input, steps, materials, output, and stop points connect? Have high-risk protections, the purpose of each supporting file, script permissions, and dependencies been checked? Have you run the paired tests with related and unrelated tasks? For how to organize the files so they load on demand, see how to structure a Claude Code skill folder.

Whether a skill is ready for the team comes down to the evidence you can show: call logs and read logs proving it turns on when it should and stops when it should.