Wisdom

Help your Claude Code work more efficiently and effectively, like me

繁體中文

Wisdom is the set of Claude Code skills I use every day, packaged as one plugin so you can use them the way I do.

Installation

/plugin marketplace add cmj0121/wisdom
/plugin install wisdom@wisdom

Concept

v3 is a rewrite from scratch around three rules.

1. One skill, one purpose. Each skill does one thing and is named after it. A skill that needs a second job calls the skill that owns it instead of growing one.
2. Shortcuts where they help. Every skill runs with /wisdom:<name>. A skill used often enough to type in passing also declares a magic word — say smith and a prompt hook starts the lead skill. Words are unique across the plugin.
3. Fewer tokens. A description is loaded in every session, so it stays one short sentence. A body is loaded each time its skill runs, so it stays short too; anything only some runs need lives in references/ and is read only then. No personas, no role-play framing, no repeated project discovery: the plan file carries the context forward. Two hooks keep a long session on course: one repeats the lingua language on every prompt, the other re-injects PLAN.md after compaction while a unit is unfinished.

Skills

smith is the entry point. Tell it what you want built and it plans the work, then calls the other skills in turn. Every skill also works on its own.

Lead

Skill	Purpose	Magic word
smith	Drive a piece of work from idea to merge using the skills below	smith

Build

Skill	Purpose	Magic word
plan	Turn an idea into PLAN.md and PLAN_DETAILS.md: units, decisions, setup	plan it
architecture	Decide an architecture, API or tech choice, preferring vetted code	architect it
spec	Write a technical specification for an agreed design	write spec
code	Implement one unit of work with its tests	code it
test	Run the project's test suite and report the result	run tests
review	Review a diff for correctness and quality	review it
docs	Write or update user-facing documentation	document it

Ship

Skill	Purpose	Magic word
commit	Commit what is staged, with a written message; fail if nothing is	commit it
history	Classify a branch, then reshape it: bump, docs, feats, one test	—
changelog	Generate changelog entries from git history	gen changelog
release	Bump the version and tag a release — only when asked	release it
resolve	Work a pull request's review comments, test first	resolve pr

Check

Skill	Purpose	Magic word
secure	Review source for security issues, mapped to CWE	sec review
audit	Audit dependencies for known vulnerabilities and staleness	audit deps
ops	Review operational readiness before a release	ops review
challenge	Argue against a plan and name its blind spots	tenth man
lsp	Say whether the repo needs a language server, and which	need lsp

Output

Skill	Purpose	Magic word
diagram	Draw an ASCII diagram of a decided structure	draw a diagram
assets	Build media assets one confirmed change per round	build assets
compact	Re-render the previous answer as a dense table	compact it
brief	Keep answers short and discuss one topic at a time	brief me
afk	Work to the end and ping you when done or needed	afk mode
hold	Stop the task and its background work; resume it later	hold and wait, keep go on
lingua	Answer in your chosen language, remembered per project	reply in
shortcut	List every magic word, or dispatch one the hook missed	—

afk rings the terminal (bell + OSC 9) when the agent stops; afk off ends it. It does not change the permission mode: a permission request still stops the agent, and is the needs-you ping. Terminal.app shows no OSC 9, so there the message arrives through Notification Center, listed under Script Editor — allow its notifications. Under tmux only the bell gets through unless passthrough is on. Claude Code's own notification channel, if you set one, pings as well.

hold acts at the next turn boundary: a step already running finishes first, and only Esc interrupts it. hold and wait stops the task's background agents, workflows and shells and records them; keep go on resumes from the recorded step. With a PLAN.md the hold is recorded there and survives compaction; without one, a compaction can lose a long hold. afk yields to a hold.

How smith runs

A boxed step runs in its own subagent; a smith ─ step is Smith itself; ★ waits for you.

① Plan & Architecture

  smith ─ wisdom:plan ──> PLAN.md + PLAN_DETAILS.md
                │
                ▼
      ┌───────────────────┐
      │ wisdom:challenge  │
      └───────────────────┘
                │
                ├──PAUSE──> smith revises, same challenger re-checks
                ├──RECONSIDER──> ask user
                │ GO
                ▼
  ★ Checkpoint 1 · user approves plan
                │
                ▼
  smith ─ wisdom:architecture / wisdom:spec ──> architecture units marked done
                │
                ▼
             ② Build

② Build · repeated per batch

  ┌──────────────────────┐ ┌──────────────────────┐
  │ wisdom:code · U1     │ │ wisdom:code · U2     │   parallel, one worktree each
  └──────────────────────┘ └──────────────────────┘
             │                        │
             ▼                        ▼
  ┌──────────────────────┐ ┌──────────────────────┐
  │ wisdom:review · U1   │ │ wisdom:review · U2   │   parallel
  └──────────────────────┘ └──────────────────────┘
             └───────────┬────────────┘
                         ▼
  smith ─ routes VERDICT lines ──design wrong──> smith ─ wisdom:architecture
                         │
                         ├──FAIL──> same code agent fixes ──> same reviewer re-checks
                         │ PASS
                         ▼
  ┌──────────────────────────────────────────────┐
  │ same code agent · git add + wisdom:commit    │   resumed via SendMessage
  └──────────────────────────────────────────────┘
                         │
                         ▼
  smith ─ merges each branch into feat/<slug>
                         │
                         ▼
  smith ─ runs the full suite on feat/<slug>   once per batch, unless reused
                         │
                         ├──non-zero──> wisdom:test names failures ──> new wisdom:code agent ──> review, commit, suite
                         │ exit 0
                         ▼
  smith ─ Baseline = PASS at <sha> ──> next batch, or ③

③ Check & Merge

  ┌─────────────┐ ┌───────────────┐ ┌──────────────┐ ┌────────────┐
  │ wisdom:docs │ │ wisdom:secure │ │ wisdom:audit │ │ wisdom:ops │   only those needed
  └─────────────┘ └───────────────┘ └──────────────┘ └────────────┘
         └────────────────┴────────┬───────┴───────────────┘
                                   │
                                   ├──BLOCKED, FINDINGS, BLOCK──> new wisdom:code agent ──> review, commit
                                   ▼
           ┌──────────────────────────────────────────────┐
           │ wisdom:history · classify, then reshape.py   │   bump, docs, feats, one test
           └──────────────────────────────────────────────┘
                                   │
                                   │ any result · ABORTED: branch unmoved, shown at Checkpoint 2
                                   ▼
           smith ─ runs the full suite, whatever history returned
                                   │
                                   ├──FAIL──> fix, commit ──> back to wisdom:history
                                   ▼
               ★ Checkpoint 2 · user approves merge
                                   │
                                   ▼
  smith ─ git merge --no-ff into main · rm PLAN.md PLAN_DETAILS.md

• plan writes two files once, and every later skill reads them instead of rediscovering the project: PLAN.md, the short view smith reads — units, decisions, verdicts — and PLAN_DETAILS.md, what a subagent needs to start cold — setup, baseline, each unit's files and acceptance, each decision's interface.
• Every step on a unit runs in a subagent; smith reads result lines, never diffs.
• Independent units run in parallel, each code in its own git worktree, running only its own tests; the full suite runs once per merged batch. smith runs it itself and delegates only a failure.
• review returns a one-line verdict; smith routes a failure back to the same code subagent (or to architecture when the design is at fault), which commits once it passes.
• Before the merge, history classifies the unpushed branch's files and commits, then calls reshape.py, which rebuilds it as linear history in a temporary worktree; its empty diff against the start is why reviews are not run again. smith then re-runs the suite whatever history returned, since the commits from the check step have not been tested.
• smith stops at two checkpoints, to approve the plan and the merge, and also when it needs your answer or a hard-to-undo choice, when work is left unreviewed or untested, or after two failed fix rounds; its skill has the full routing. It never tags, releases or pushes unless you ask.

Token budget

Part	Loaded	Budget
description	every session	one sentence, ≤ 160 characters
SKILL.md body	each time it runs	≤ 100 lines (smith ≤ 150)
references/*.md	only when a run needs it	no limit, one topic per file

Development

Skills are Markdown with YAML frontmatter following the Agent Skills standard; there is no build step.

plugins/wisdom/
├── .claude-plugin/plugin.json
├── evals/<case>/        # what `make eval` runs
├── hooks/               # hooks.json and the scripts it runs
└── skills/<name>/
    ├── SKILL.md
    ├── references/      # optional
    └── scripts/         # optional

Run make test before a commit — it checks the layout, the version sync, magic words and README tables, frontmatter against the standard, hook output, and history's reshape.py. make eval runs the skill evals with real, billed model runs, capped at $5 a run; CI does not run it.

DDD (Dream-Driven Development)

This project follows DDD (Dream-Driven Development): it is driven by what I envision. Every feature comes from my own needs and my own dreams.