v2.6.0 — The Skills Compliance Release

Every meow:* skill was audited against Anthropic's Skill authoring best practices + Lessons from Building Claude Code + MeowKit's own skill-authoring-rules.md. This release is what that audit turned into — ~220 edits across 77 skills, no new features, no breaking changes, measurably better routing.

Highlights

• Description discipline across the catalog. Four skills had greedy / imperative descriptions (meow:cook, meow:fix, meow:agent-detector, meow:session-continuation) that cannibalized sibling routing in a 77-skill catalog. All rewritten in third person per Anthropic's spec. Five overlap clusters (bug-fix, pipeline, browser, code-quality, planning) got explicit NOT for X (see meow:Y) exclusion clauses so Claude stops picking the wrong tool.
• meow:skill-creator is now itself compliant. It was previously missing ## Gotchas (ironic, given it scaffolds other skills), enforcing a 150-line cap that contradicted the authoritative 500-line rule, and emitting templates without the mandatory Gotchas header. Fixed in both SKILL.md and the scripts — every future scaffold inherits Rule 1 / Rule 3 compliance.
• Reference integrity pass. meow:agent-browser's 8-deep nested ref chains + authentication.md ↔ session-management.md circular ref were flattened. Step-file skills now have a formal architectural exception (step-file-rules.md Rule 6) for SKILL.md → step-NN.md → references/X.md chains, predicated on each step file opening with a Contents TOC.
• Grounding cleanup. Phantom research-01 citations in meow:evaluate (4 locations) and phantom research-02 citations in meow:rubric / meow:sprint-contract / .claude/rubrics/schema.md were load-bearing for operational constraints but pointed at files that never existed — removed or re-sourced. Non-existent debugger agent reference in meow:cook replaced with the real developer via meow:investigate. Unverifiable "Vercel Engineering" attribution in meow:react-patterns rephrased.
• 115 Tables of Contents auto-generated for reference files over 100 lines. The audit's original estimate was 25; actual was 116 (4.6× under-count, largely from meow:angular).

What the routing looks like now

The 77-skill catalog routes user intent through description fields at startup. A user typing "debug this bug" must unambiguously land on one skill. Before this release, five clusters had ambiguous routing. After:

Cluster	Member	NOT for (routes elsewhere)
Bug fix	meow:fix	investigation without fix → meow:investigate
	meow:investigate	applying fixes → meow:fix
	meow:build-fix	runtime errors → meow:fix
Pipeline	meow:cook	green-field product → meow:harness
	meow:workflow-orchestrator	single-task → meow:cook
	meow:harness	scoped single-task → meow:cook
Browser	meow:browse	session-persistent → meow:playwright-cli
	meow:playwright-cli	AI-autonomous → meow:agent-browser
	meow:agent-browser	.spec.ts generation → meow:qa-manual
	meow:qa-manual	unstructured browsing → meow:browse
Code quality	meow:review	running-build verification → meow:evaluate
	meow:clean-code	post-hoc diff review → meow:review
	meow:simplify	style enforcement → meow:clean-code
	meow:evaluate	structural code audit → meow:review
Planning	meow:plan-creator	ticket complexity → meow:planning-engine
	meow:planning-engine	implementation plans → meow:plan-creator

Plus 20 more skills picked up focused NOT for X clauses where overlap was latent.

Frontmatter normalization

Field	What changed	Scope
preamble-tier	4 → 3 (valid range per CLAUDE.md is 1-3)	meow:qa, meow:review, meow:ship
autoInvoke / priority	Deleted (grep-confirmed zero readers in hooks / scripts / CLI)	meow:agent-detector, meow:workflow-orchestrator, meow:session-continuation, meow:lazy-agent-loader
sources (plural)	Unified to source (singular); array syntax for multi-origin	7 skills (bootstrap, sequential-thinking, problem-solving, brainstorming, ui-design-system, react-patterns, docs-init)
injection_risk	low → medium (external content replication)	meow:chom

version, phase, and allowed-tools backfill was skipped by design — grep across packages/mewkit/src/ confirms no hook or CLI consumer reads per-skill version or phase, and allowed-tools omission gives default (all-tools) permissions which is the safer default for skills whose needs vary.

Reference integrity

• meow:agent-browser — 8 inter-ref cross-links removed from 6 reference files (authentication, session-management, profiling, proxy-support, snapshot-refs, video-recording, plus 2 inline refs in advanced-features). Circular authentication ↔ session-management broken. All 9 reference files remain directly linked 1-level from SKILL.md.
• meow:docs-finder — workflows/topic-search.md → library-search.md chain resolved by converting the direct link to prose name-reference.
• step-file-rules.md Rule 6 — new rule formalizing that step-file skills (meow:review, meow:trace-analyze, meow:plan-creator, meow:harness, meow:evaluate) MAY use 2-level SKILL.md → step-NN.md → references/X.md chains, provided each step file opens with a ## Contents TOC.
• 7 skills gained a > Path convention: note declaring $CLAUDE_PROJECT_DIR as assumed cwd for their command invocations (meow:rubric, meow:multimodal, meow:skill-creator, meow:intake, meow:llms, meow:investigate, meow:jira).
• 3 MCP skills (meow:jira, meow:confluence, meow:planning-engine) gained a Gotcha documenting the .mcp.json server-key assumption (atlassian) without hardcoding prefixes — preserves portability across user installations.
• meow:help and meow:scale-routing cross-skill refs documented as intentional architectural dependencies via Gotchas rather than silent imports.

meow:skill-creator hardening

Three fixes make the scaffolding source-of-truth for all future skills compliant with skill-authoring-rules.md:

1. SKILL.md now has a ## Gotchas section (fixes its own Rule 1 violation), and its compliance checklist says 500-line cap (Rule 3) instead of a contradictory 150.
2. scripts/init-skill.py template emits ## Gotchas with a (none yet — grow from observed failures) placeholder by default. Every new skill inherits the mandatory header.
3. scripts/validate-skill.py line cap raised 100 → 500 to match Rule 3, with an auto-pass for step-file skills (those with workflow.md). A new check 8/8 enforces ## Gotchas header presence.

Script fixes

• meow:rubric/scripts/validate-rubric.sh — --help / -h handler added at the top of the arg dispatcher. The previous version fell through to basename "--help" which BSD basename (macOS) rejects with illegal option. Verified on macOS.
• meow:multimodal/scripts/minimax_api_client.py — poll_interval=10 and max_wait=600 now carry a docstring explaining derivation (MiniMax video-gen p50 ~60-120s, p99 ~600s).
• meow:multimodal/scripts/media_optimizer.py — tokens_per_sec = 100 / 263 constants sourced to ai.google.dev/pricing verification date.
• meow:multimodal/SKILL.md — check_setup.py got a missing bash invocation block (every other script had one).

Grounding fixes

• research-01 citations removed from meow:evaluate/SKILL.md (2), step-01-load-rubrics.md, and prompts/skeptic-persona.md — no such file exists in the repo; the constraints (15-criteria cap, "leniency drift is the dominant evaluator failure mode") now cite the Anthropic harness research honestly or state themselves as heuristics.
• research-02 citations removed from meow:rubric/references/calibration-guide.md (2), meow:sprint-contract/SKILL.md, meow:sprint-contract/references/bdd-to-ac-mapping.md (2), and .claude/rubrics/schema.md. Same non-existence; balance-rule rationale now cites Anthropic harness research.
• Non-existent debugger agent replaced with developer via meow:investigate in meow:cook's Phase-3 dispatch table (.claude/agents/ has no debugger.md; developer.md is the real agent).
• <HARD-GATE> decorative tags in meow:cook and meow:fix bodies replaced with **HARD GATE** bold. grep -rn "HARD-GATE" .claude/hooks .claude/scripts scripts/ returned zero consumers — confirmed decorative.
• meow:multimodal "332 system voices" corrected to 300+ (see provider catalog) with the MiniMax URL.
• meow:react-patterns "45+ rules across 8 priority categories from Vercel Engineering" (unverifiable) → "curated rules drawn from framework docs and production practice".
• meow:vulnerability-scanner dropped time-anchored "2025 threat landscape" tagline.
• meow:ui-design-system CSV row claims corrected: colors.csv 161→160, ux-guidelines.csv 99→98 (matches actual row counts).
• meow:scout 6-agent cap now documented as an intentional exception to parallel-execution-rules.md Rule 2 (read-only Explore agents, no merge-conflict risk — no rule edit needed).
• meow:browse gained a Gotcha for the session-scoped $B alias silent-fail mode.
• meow:problem-solving line 148 unclosed backtick fixed.

Section-name canonicalization

22 skills had drifted across four trigger-section synonyms. All converged to "When to Use" (the most common variant, matches Anthropic's wording):

Before	Count	After
## When to Invoke	10	## When to Use
## When to Activate	5	## When to Use
## Trigger Conditions	7	## When to Use

grep -rn '^## (When to (Invoke|Activate)\|Trigger Conditions)' .claude/skills/ returns zero after this release.

Phase 01 critical blockers

Three issues that were silently broken before this release:

1. meow:lint-and-validate YAML frontmatter — malformed Triggers onKeywords: produced an unquoted colon that corrupted YAML parsing. The skill was undiscoverable by Claude's skill loader. Frontmatter now parses cleanly.
2. research-01 / research-02 phantom citations — see grounding fixes above.
3. Empty Python venv — .claude/skills/.venv/ existed but pip was half-installed (no RECORD file, no bin/pip symlink). All 7 Python-backed skills (meow:web-to-markdown, meow:multimodal, meow:llms, meow:confluence, meow:planning-engine, meow:skill-creator, meow:plan-creator) crashed on first import. Bootstrapped via get-pip.py --ignore-installed --no-deps, then npx mewkit setup --only=deps installed 9 required packages. npx mewkit doctor now reports 13 PASS / 1 WARN (only optional Playwright).

Audit artifacts

Seven agent reports (structure, scope & boundary, reference integrity, consistency, implementation, grounding, lead aggregation), a red-team review with 15 attacks + amendments, and the seven phase files that drove execution. The TOC generator script is reusable for future drift cleanup.

Migration Notes

• npx mewkit upgrade picks up all description changes. No user action required beyond upgrade.
• If you had any skill depending on autoInvoke / priority frontmatter fields, note they were confirmed dead before deletion. If you had a custom hook reading them, it was already silently ignored.
• preamble-tier: 4 → 3 may cause tiny context-ordering shifts for meow:qa / meow:review / meow:ship. Functionally identical outputs.