Skills

What this layer is / Why it matters

A skill is a saved workflow: a folder with a SKILL.md that tells Claude how to do one job the same way every time. Subagents are helpers Claude hands work to. Together they turn "explain it again" into "type one phrase".

Why it matters: without skills every session re-invents how to plan, review and verify. With them the process is repeatable, and you improve it in one place.

A rule goes in CLAUDE.md, a fact goes in memory, a procedure goes in a skill, a big isolated job goes to a subagent.

Core: the real stack

These are the skills that got used, counted from about two months of real work across two accounts. Most are community packs (install commands in skills/PACKS.md). Two are written by this kit. Taught as a workflow, in the order a piece of work moves:

Most used, ranked

Rounded uses in about two months of real work. Treat as a shape, not a benchmark.

Model choice and subagents

A subagent runs in its own context and returns a summary, keeping your main conversation clean. Use them to read many files, search, scrape, run tests, and do independent tasks in parallel.

Tier the model to the job. Mechanical work (grep, tables, copying, scraping) goes to a cheap fast model. Judgment, design and core code stay on the strongest. Eleven top-tier agents in parallel burn your usage limit; parallel is good, parallel and expensive is not. Switch with /model or set it per subagent.

Skill anatomy (when you write your own)

~/.claude/skills/<name>/
  SKILL.md        required: frontmatter (name, description) + steps
  helper.sh       optional scripts
  reference/      optional long docs, read only when needed

The description is the trigger: what it does, then "Use when asked ..." with 4-8 phrases a person would really type, including casual ones. Write a skill only after you have done the job three times.

Optional: life-OS skills

Six starter skills ship in skills/: daily-briefing, weekly-planning, priority-coach, recall, memory-prune, delegate-brief. /onboard fills their {{PLACEHOLDERS}}.

Honest take: in real use, the briefing, planning, priority and delegate skills were almost never typed. They earn their keep as scheduled jobs that run on their own and drop the output in your inbox or a file (doc 05). recall is the exception to try interactively. Install them if you want automation, skip them if you mostly code. Maya's Monday briefing from Acme Corp meetings and Sunday plan across Northlight Studio, Ridge Coffee and Clinicly are the use case.

Advanced (developers)

1. Write the description first. If you cannot list trigger phrases, the skill is not defined.
2. Extract steps from a real transcript where the workflow went well.
3. Test in a fresh session with each trigger phrase, then a near-miss that should not fire.
4. Put deterministic work in scripts (see recall/search.sh); let Claude judge.
5. Review with superpowers:writing-skills or anthropic-skills:skill-creator. Keep the folder in git.

Skills that touch outside systems: read-only by default, confirm before writing, never send without showing the text.

One skill pool across accounts. Each account has its own config dir (~/.claude, ~/.claude-work) and cannot see the other's skills. Keep one pool and symlink one way:

#!/bin/zsh
SRC="$HOME/.claude/skills"
for DST in "$HOME/.claude-work/skills"; do
  mkdir -p "$DST"
  for s in "$SRC"/*(N-/); do
    name="${s:t}"; tgt="$DST/$name"
    if [ -L "$tgt" ]; then [ "$(readlink "$tgt")" = "$s" ] || ln -sfn "$s" "$tgt"
    elif [ -e "$tgt" ]; then echo "keep own copy: $tgt"
    else ln -s "$s" "$tgt"; fi
  done
done

Never overwrite a real folder; work-only skills stay in the work account (NDA). Plugins are per account: repeat /plugin install in each.

Lessons from real use

• The stack is process, not life admin. The most-used skills were about deciding, planning, building, seeing and verifying work. Briefing-style skills belong on a schedule.
• Too many overlapping skills. At 100+ skills, three offered "review", two "debug", and Claude picked inconsistently. One owner per job.
• Plugin duplicates. The same skill arrived as a plugin and a pool folder. Check /plugin and the skills folder first.
• Descriptions beat bodies. Most "it didn't fire" bugs were weak trigger phrases.
• Hard-coded personal details rot. Use {{PLACEHOLDERS}}.
• Cheap model for grunt work cut usage sharply with no quality loss.