Claude Code Skills for Beginners: Behavior Contracts That Do Not Rot

A Claude Code skill is not a longer system prompt.

It is a behavior contract the agent can load when the task matches - scoped, versioned, and reusable across sessions.

This guide is for developers who have opened Claude Code, shipped a few vibes, and want skills that do not rot.

Kill the default approach

Default: paste a longer system prompt every session, or hoard 40 "skills" nobody runs.

What breaks first: forgotten rituals, conflicting triggers, verify steps that never ran.

By the end you will have

1. A clear prompt vs skill vs agent table
2. The Skill Contract Template (magnet)
3. Auto-invoke mental model
4. Monthly prune rules
5. A beginner exercise that ships skill #1

Prompt vs skill vs agent

If you retype the same instructions three times, promote them to a skill.

Anatomy of a useful skill

Good skills have:

1. Name and when to use - trigger conditions in plain language
2. Steps - ordered actions, not vibes
3. Verification - commands or checks that prove done
4. Out of scope - what the skill must refuse
5. Examples - one happy path, one edge case

Bad skills are novels. The agent skims; you get improvisation.

Magnet: Skill Contract Template

Name: Skill Contract Template

# skill: pr-hygiene
 
## When
Creating or updating a pull request for this repo.
 
## Steps
1. Run the project typecheck / test script.
2. Summarize the diff in 5 bullets max.
3. Propose a conventional commit title.
4. List residual risks.
 
## Verify
- typecheck exits 0
- no secrets in the diff
 
## Do not
- force-push
- edit lockfiles without stating why

You should see: skill used twice on real work with verify green before you write skill #2.

Ship that before you invent an "ultimate skill OS."

How auto-invoke should feel

When skills work, you stop pasting rituals. You say the task; the right contract loads; the agent follows the checks.

When skills fail, every task becomes a new negotiation. That is the smell of missing or conflicting skills.

Failure modes

Skills rot when:

• The repo scripts changed and the skill still names old commands
• Two skills claim the same trigger
• Nobody prunes monthly
• Verification steps were never real

Monthly prune:

1. Delete skills unused in 30 days
2. Fix broken verify commands
3. Merge near-duplicates
4. Keep one owner per skill

Production habits

• One skill per workflow, not one mega-file
• Prefer repo-local skills for product code; personal skills for personal ops
• Never put secrets in skill text
• Log when a skill was last proven green

When not to write a skill

• You have not repeated the ritual three times yet
• The "skill" would only restate the model system prompt
• Verify commands are unknown (fix the green command first)
• The workflow needs a human legal/compliance decision every time

Where this fits the wider stack

Skills are layer-4 harness material. They sit above the model and beside tools. They do not replace context engineering or tests.

Further reading:

• The harness is the product
• 4 layers of AI work
• Agent OS checklist
• Verification loop

Beginner exercise

1. Pick your most repeated Claude Code ritual
2. Write the Skill Contract Template in 15 minutes
3. Run it twice on real work
4. Fix the verify section after the first failure
5. Only then write skill #2

Two proven skills beat twenty aspirational ones.

Bottom line

Skills are contracts with verify, not novels.

Your next action: write Skill Contract Template for your most repeated ritual today and run verify once.

Package help: Agent OS Setup. OSS: catalog.