Skill Usage and Design

Recap

recap · part 01

Skills live in the Behaviors layer.

01

Common Skills

what people use

02

Skill Design

write your own

03

Skill Symlinks

share across

Section 1
Common Skills

A minimal `SKILL.md`

SKILL.md

---
name: api-conventions
description: REST API conventions
---
# API Conventions
- kebab-case URL paths
- camelCase JSON properties
- pagination on every list endpoint
- version in path (/v1/)

  auto-trigger
  on context
  · or ·
  manual
  via /name
 

Where skills come from

Plugins

~10%

bundled sets via /plugin

Curated sets

~20%

tw93's Waza

★ most used

Your own

60–80%

grow with usage · dominate after months

  share of daily use, after a few months
 

What people use them for

code review

/review /security-review

refactor

/simplify /refactor

tests

/tdd /e2e

build / verify

/build-fix /verify

docs & git

/init /commit

knowledge

/think /learn

  80/20 kicks in fast — optimize what you actually use
 

Section 2
Skill Design

Anatomy of `SKILL.md`

SKILL.md

— frontmatter —
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
— body —
1. gh issue view
2. search the codebase
3. implement the fix
4. write & run tests
5. commit, push, open PR

name

Becomes /name. Keep short.

description

Powers auto-trigger.

disable-model-invocation

Opt-out for side-effect skills.

The load-bearing section

"

The most valuable content in any skill is the Gotchas section.

   — Anthropic, Building Skills for Claude
  

Gotchas = where your tribal knowledge lives.

A Gotchas-rich skill

deploy-staging/SKILL.md

## Steps
…
## Gotchas
- migration must finish BEFORE API redeploys
- npm build succeeds even if env vars missing
- CDN purge takes 90s
- don't claim done until smoke test passes

  difference between "kind of works" and actually reliable
 

Design principle 1

design principle 01

Less is more.

4–8

chars per name

6–10

active skills

long

name = too many

  bundle wins once. focused set wins daily.
 

Design principle 2

design principle 02

Define the negatives.

✕ vague

"code review for security"

✓ sharp

"security review — do NOT run on docs, refactors, formatting"

  underused. steal it.
 

Skills as advanced Context Engineering

re-framing

Skills are essentially an advanced practice of Context Engineering.

  Context Engineering
  ⊃
  Skills
  ⊃
  Progressive Disclosure
 

They solve a very real problem: how to give the model the right info at the right time.

The attention problem

Cram every tool, instruction, parameter into the context →

attention disperses.

overload

  context windows are a scarce resource — more info ≠ better answers
 

Design principle 3 — progressive disclosure

how skills handle it

Progressive disclosure.

step 01 · always-loaded

Just metadata

 Skill A: search

 Skill B: data analysis

 Skill C: charting

→

step 02 · on trigger

Dynamic load

 Skill A

 Skill B → full body 

 Skill C

on demand

only what the task needs

layered

metadata → details → assets

at the right time

when actually triggered

How to actually write a skill

  don't start from a blank page
 

1

do

By hand once

Get it right.

2

extract

Ask Claude

"Turn this into SKILL.md."

3

drop in

Save & test

Try on next task.

4

refine

Update over time

Misfires → Gotchas.

Complete a real run first. Then extract the rule.

Skills vs `CLAUDE.md` vs rules

CLAUDE.md

always behave

every session

always loaded

"always do this"

rules/*.md

when to know

topical knowledge

on demand

"when you need to know X"

skills/X/SKILL.md

when to do

reusable workflow

on invoke

"when you need to do X"

Skill anti-patterns

kitchen-sink

/do-everything branching into 10. Split it.

CLAUDE.md duplicate

Restates rules already loaded. Delete one.

auto-trigger landmine

Side-effect skill without disable-model-invocation.

?

unverified

No "how to confirm it worked." You'll catch failures by hand.

Section 3
Skill Symlinks

The problem

  A  ✓ /commit
  →
  B  ?
  →
  C  ?
 

✕ Copy-paste

Drifts the moment you improve one.

⚠ Plugin

Real solution. Overkill for one or two.

✓ Symlink

Lightweight middle path.

Two patterns

pattern A

Global folder

simplest

~/.claude/skills/<name>/
↓
project/.claude/skills/

· ln -s per project
· add to .gitignore

pattern B

Skills repo

version-controlled

~/code/my-skills/
↓ pick & link
project/.claude/skills/

· canonical in a git repo
· bonus: shareable

A complete example

setup once · link per project

# 1. canonical skill
$ mkdir -p ~/.claude/skills/commit
$ echo "..." > ~/.claude/skills/commit/SKILL.md
# 2. link from project
$ cd ~/code/my-project
$ ln -s ~/.claude/skills/commit .claude/skills/commit
# 3. don't ship the link
$ echo ".claude/skills/commit" >> .gitignore

  /commit works here · update once → all linked projects get it
 

Important guardrails

✓ do

· symlink individual skill folders
· add to .gitignore
· track canonical in git
· use absolute paths

✕ don't

· symlink whole .claude/
· commit symlinks to git
· cross machines without sync
· use relative paths

When to graduate to a plugin

symlinks great for 1–5 skills

— signals to graduate —

Coherent set that belongs together.

Want to share with a teammate.

Bundle skills + MCP + hooks.

Same source of truth. Plus distribution.

Three takeaways

✓

Common skills

Best ones are your own. Optimize the 6–10.

✓

Skill design

Gotchas is load-bearing. Less is more. Define negatives.

✓

Skill symlinks

One canonical, link in, .gitignore the link.

Up next

— part 03 —

Data Safety
with AI

ch 01

Counter-productivity of AI

ch 02

The data-science dilemma

ch 03

A successful workflow