Claude Rules for Skills

PDF

File:The 10 SKILL Rules.pdf

Progressive Disclosure

Claude only loads what it needs when it needs it.

Try to keep main skill file under 500 lines for performance. Everything else need to go to their own files and linked in main skill file.

Best practice : Keep reference one level deep from SKILL.md. All reference files should link directly from SKILL.md Like

• SKILL.md
  • reference.md
  • examples.md
  • FORMS.md

Prompt to audit existing skills

Go through my 5 most used skills. For each one, tell me if SKILL.md is over 500 lines, list every file it links to, and flag any file that is only reachable through another file. Shoe me the list before you change anything.

Content Lists

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.

Prompt

Add a "Contents" heading at the top with one line per
section, in the same order as the file.

Degrees of Freedom

Match the level of specificity to the task's fragility and variability.

Narrow bridge with cliffs on both sides: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom)." "Open field with no hazards: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom).

Prompt

Lock costly steps to an exact script or command. Loosen the
rest to a plain goal. One skill can mix all three: the invoice
email wide open, the step that creates the invoice locked to
a script.

Testing skills on the models you use

Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.

Prompt

Older, step-by-step instructions: test with them removed,
and keep the cut only if the output is as good or better.

Optimise your skill writing

Keep only what Claude can't work out alone, and write the description in the third person.

"The context window is a public good." "Only add context Claude doesn't already have." Ask: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

"Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems." The description "should include both what the Skill does and when to use it."

The Fix

Cut to your own facts: prices, terms, clients, internal rules.

Write "Creates client invoices and sends payment
reminders", not "I can help you with invoices and payment
reminders".

Workflows and checklists

Lay long jobs out as clear steps, give Claude a checklist it copies and ticks, and add a go-back line after every check.

"Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses."

"Clear steps prevent Claude from skipping critical validation." Anthropic's own example ends: "If verification fails, return to Step 2."

Copy this checklist and track your progress:
- [ ] Step 1: Pull this month's completed jobs
- [ ] Step 2: Match each job to the client and the price
- [ ] Step 3: Create the invoices
- [ ] Step 4: Check every total against the job list
- [ ] Step 5: Send them out
If any total doesn't match the job list, go back to Step 2.

Fix

Number the steps, add the copy-this checklist, and put a goback line under each check step

Feedback loops

Have the skill check its own work: run a check, fix what fails, and repeat until it passes.

"Common pattern: Run validator → fix errors → repeat. This pattern greatly improves output quality."

The check doesn't have to be code. In Anthropic's first example, "The 'validator' is STYLE_GUIDE.md, and Claude performs the check by reading and comparing."

"Make validation scripts verbose with specific error messages such as "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues."

Fix

• Add a short checklist to review against, a revise step, and

"only finish when every check passes".

• Make error messages name the problem and what does

exist.

Common patterns

When the output needs a set shape, use a template, examples, or a fork in the road.

Fix

Add the strict or default line, two or three real example pairs, and an "if this, follow these steps" fork.

Buildfor shareability

Never assume the tools your skill needs are installed on someone else's computer. Name them, with the install line.

Fix

Add a short "Needs" list to SKILL.md with each install line. Swap personal paths for paths inside the skill folder.

Hooks for must-hold rules

If a rule has to hold every single time, move it out of the words and into a hook.

"Claude skipped a rule that must hold every time: move the rule into a hook. Claude Code runs a hook every time its event occurs, such as before each file edit, whether or not Claude is following the skill. To keep the rule with the skill, define the hook in the skill's hooks frontmatter. That hook applies from the time the skill is invoked until the session ends."

The hooks frontmatter field: "Hooks that Claude Code registers when the skill is invoked and keeps running for the rest of the session."

Fix

• Pick the few rules where one mistake really costs you, and make those your hooks.
• Keep the rest as plain words, with the reason beside them.

Put your most important instructions at the top

In a long Claude Code session, only the start of a skill may survive, so the rules that matter most go first.

Never tell Claude to writeout its reasoning =

On the newest models, a skill that asks Claude to echo its thinking in the reply can get the request declined.

Skill Creator Plus

https://github.com/robonuggets/skill-creator-plus

What it does?

Audit

Usage : "Audit my deploy skill against Anthropic's rules." Or: "Check every skill in ~/.claude/skills and tell me what to fix first."

You Get : A report: one row per rule, fails first, ranked fixes. Nothing is edited until you pick.

New

Usage : "Make this a skill, we write release notes like this every Friday."

You Get : Test prompts first, then a new skill folder that passes the validator.

Refine

Usage : "The report skill keeps forgetting the date filter. Fix the skill."

You Get : The rule rewritten around its reason, usually shorter than before.