claude-skills: Instructions file for Claude Code

claude-skills

Public, machine-agnostic rewrites of six Claude Code skills (project-init, handoff, drift-check, qa-audit, token-audit, model-alignment-audit), stripped of any personal or machine-specific setup so anyone can install them.

Check docs/WORKLOG.md for the current task list and recent session notes before starting work.

What this is

A public repo of installable Claude Code skills. Each skill is a folder with a SKILL.md, no build step, no dependency on any private repo. Rewritten from private originals in ~/my-ai-agent to strip personal/machine-specific setup (names, canary tokens, Cursor linkage scripts, ~/my-ai-agent paths, rulesync-specific mechanics).

Key decisions

• [2026-08-30] Ran an interactive README accuracy pass against each skill's actual SKILL.md behavior: confirmed all six skill blurbs matched real behavior, fixed one real bug (project-init/assets/context-router-indepth.md's step comment said "Step 5b," should be "Step 6"), and fixed qa-audit/token-audit's README target lists, which omitted slash command files despite both skills covering them. Also restructured README's Skills section into "Project workflow" (project-init, handoff, drift-check) vs. "Audit skills" (qa-audit, token-audit, model-alignment-audit) with a comparison table, and rewrote all six taglines from mechanism-first to outcome-first, the originals described what a skill creates, not why it matters.
• [2026-08-17] Audited this repo against a same-session pass over the private ~/my-ai-agent skills library (guidance/model-fit issues, not token bloat). Two real bugs matched and were fixed here: (1) qa-audit/token-audit Step 1's code-file guard was inverted, "code if extension isn't .md" wrongly rejected .json/.yaml/other config files as code; fixed to an explicit code-extension check, then recognized-.md-location check, then ask-to-confirm for everything else. (2) handoff Step 6 stated the decision-log cap as 15 entries, contradicting references/decision-log-maintenance.md's actual 8 (which matches this file's own archive behavior); fixed to 8. Other items on the private-repo list didn't apply here: no relative bundled-script paths in project-init, no CLAUDE.md/drift-check auto-trigger contradiction, no 3+ tier risk rubric, no missing negative triggers, and the mechanical-steps-run-without-pausing note was already present in handoff Step 9. Also ported the private repo's new model-alignment-audit skill (Anthropic-guidance-and-model-fit audit, distinct from token-audit's bloat focus) as this repo's sixth skill, stripped the same way as the others: no targets: field, sync-tool language generalized, machine-specific Vertex-access section dropped in favor of a generic WebFetch/WebSearch-unavailable guard.
• [2026-07-22] Reverted part of the 2026-07-20 token-audit trim to handoff after live use showed WORKLOG.md/decision-log entries were still bloating: archive thresholds dropped back from 10/15 to 6/8, and the softened length guardrails became hard-enforced counts again, matching the same reversal already made in the private ~/my-ai-agent repo. Also ported that repo's new token-audit Mode C (refresh guidance against current Anthropic docs) and a bare-invocation menu step, and added a folder-structure diagram plus Cursor-availability tags to README.
• [2026-07-20] Ported the private repo's token-audit pass (commit c05d345) into handoff, drift-check, qa-audit, and project-init where it genuinely applied. Rejected two of its changes: its worklog-archive ordering (oldest-at-top) contradicts this repo's actual archive layout (newest-at-top, verified against docs/archive/worklog-2026-07.md), and its simplified drift-check Check 3 compaction logic loses the Check-1-vs-Check-2 distinction our version correctly makes. Also fixed a pre-existing bug found in the process: handoff Step 6 said decisions append oldest-first, contradicting CLAUDE.md's real newest-at-top log.
• [2026-07-20] Ported Claude Code slash-command file support (.claude/commands/*.md) into qa-audit and token-audit from the private repo: qa-audit gained a command-specific frontmatter checklist branch, token-audit added command files to recognized locations and the unused-item scan. Excluded the private diff's .rulesync/commands/* handling, rulesync-specific and not applicable here.
• [2026-07-09] Pulled a token-optimization pass from the private repo into handoff and project-init: inline templates (worklog starter, CLAUDE.md starters, Cursor context-router content) moved out of SKILL.md into companion assets/*.md files, loaded on demand instead of always-loaded. Kept this repo's own deliberate addition, the override-marking sentence in both context-router asset files ("the project rule wins only when it explicitly states it's overriding..."), even though the private version had dropped it, since it's a documented decision specific to this repo, not something to lose in the sync. Also ported a new guardrail into token-audit: a token cut that makes a file harder for a human to scan counts as a quality cost, flag it "uncertain," not "safe," same as a nuance-loss risk. drift-check's only private change was prose tightening (no asset split); merged its duplicated "clean" and "drifting" output-format examples into one block with inline conditional comments.
• [2026-07-09] Added token-audit as the fifth public skill, rewritten from the private original at ~/my-ai-agent/.rulesync/skills/token-audit/SKILL.md. Stripped the same way as qa-audit: no targets: frontmatter field, rulesync-managed-file resolution generalized to "if a sync tool is in use," the rulesync generate --targets ... regenerate step generalized the same way, and global-context.md naming generalized to "your global context file." The unused-skills question in Step 5 asks "the user" generically instead of by name. Scoped Claude Code only, same reasoning as qa-audit: the per-file Opus-subagent mechanic has no Cursor or Cowork equivalent.
• [2026-07-09] Pulled three protocol updates from the private qa-audit into the public version: Step 2's context-gathering narrowed from "read README/decision logs/sibling skills" to a targeted check-your-decision-log-for-matching-entries-only approach (cuts unnecessary full-file reads before spawning agents); the QA prompt template now caps each finding at 2-3 sentences with no restated reasoning; Step 4 adds a compact-report instruction and suggests compacting the conversation after a full-library run since the raw agent transcripts aren't needed once findings are compiled. All three are efficiency changes validated in the private repo first, no behavior change to what qa-audit catches.
• [2026-07-09] qa-audit hardcodes model: "opus" for its per-file subagent calls in SKILL.md. No config flag for this, changing the model means editing that line directly.