Improve SKILL.md v1.1.0: token budgeting, model allocation, Mermaid, language-agnostic

[yelban]

Summary

Compared schematic with the Cartographer skill to identify engineering improvements while preserving schematic's core strengths (semantic file grouping, deep product inference, cross-validation).

Changes to SKILL.md

• Phase 1 — Token budget estimation: Added wc -c step to estimate diff size, with tiered agent scaling strategy:

  • <50k tokens → single agent
  • 50k–200k tokens → 2–3 agents
  • 200k+ tokens → 3–4 agents (max ~150k per agent)

  Why: Previously no guidance on how many agents to spawn. Large branches wasted time with too few agents; small branches wasted cost with too many.

• Phase 2 — Explicit model allocation: Specified subagent_type: "Explore" with model: "sonnet" for file reading agents, with Opus reserved for orchestration (planning, synthesis, inference).

  Why: Sonnet offers the best cost/capability ratio for file analysis. Without explicit guidance, the skill might use Opus for all agents, increasing cost 5x with no quality benefit for file reading tasks.

• Phase 3 — Language-agnostic file listing: Replaced hardcoded git diff --stat -- '*.ts' '*.tsx' | awk '{print $1}' with git diff --name-only, removing the TypeScript/React assumption.

  Why: The original command only caught .ts/.tsx files during cross-check, silently missing changes in Python, Go, Rust, or any other language. This broke the completeness guarantee for non-TypeScript projects.

• Phase 4 — Mermaid diagrams: Changed architecture output instructions from ASCII diagrams to Mermaid (graph TB for system diagrams, sequenceDiagram for data lifecycle).

  Why: Mermaid renders natively on GitHub/GitLab, producing cleaner, more maintainable diagrams. ASCII art is hard to edit and doesn't scale well for complex architectures.

What was intentionally NOT changed

• 11-section output template — already comprehensive
• Semantic file grouping (Core/Integration/Tests/Config) — schematic's differentiating strength vs directory-based grouping
• Cross-validation phases (3 & 5) — already stronger than Cartographer's approach
• No incremental update mechanism — unlike Cartographer (snapshot-based), schematic analyzes different branches each time, making caching inappropriate

Test plan

• Run schematic on a TypeScript branch to verify backward compatibility
• Run schematic on a Python/Go branch to verify language-agnostic cross-check works
• Verify Mermaid diagrams render correctly on GitHub
• Test with a small branch (<50k tokens) — should use single agent
• Test with a large branch (200k+ tokens) — should spawn 3-4 agents

🤖 Generated with Claude Code