Optimize skills for Claude Code context efficiency

[alexei-led]

What this PR does

Optimizes all four plugin skills for Claude Code context/token efficiency while preserving your content and framework intact. No concepts are removed — content is either reformatted for better LLM consumption, condensed to activation hints where Opus already has strong prior knowledge, or split to a lazy-loaded reference file.

Why

When review or design is invoked, balanced-coupling SKILL.md loads automatically into context (~4,400 tokens). This analysis found that ~40% of those tokens are spent on content that either duplicates other sections, uses LLM-incompatible formats (ASCII art), or teaches concepts that Opus 4.6 already knows well. The changes reduce the automatic context cost to ~2,600 tokens per invocation while likely improving classification accuracy through added worked examples.

The analysis was informed by:

• Anthropic's Opus 4.6 system card (the model scores 91% on MMMLU — it knows coupling, DDD, Cynefin, Conway's Law)
• Research on LLM instruction efficiency (few-shot examples, ordered lists vs prose, token optimization)
• Claude Code skill authoring best practices (context: fork, lazy-loaded reference files, description-based routing)

---

Changes by file

balanced-coupling/SKILL.md (329 → 194 lines, ~41% reduction)

Condensed (content preserved as brief activation hints):

• Sections 1.1–1.3 (Cynefin framework explanation, modularity definition, coupling philosophy) — Opus reliably knows these concepts from training. The specific framing is kept ("coupling is a design tool", "complexity is subjective", the working memory limit) but the multi-paragraph explanations are collapsed to a focused paragraph. Section 1.4 ("The Shared Cause") is kept verbatim — it establishes the conceptual bridge that coupling drives both modularity and complexity.

• Section 3 (Fractal Geometry) — The fractal principle is already introduced in Section 2.2 ("Distance Is Relative to the Observed Level of Abstraction") with the same examples. Section 3 is collapsed to a single paragraph retaining the key instruction: always establish which abstraction level you're analyzing.

Reformatted (same content, more LLM-efficient structure):

• Integration strength levels — Converted from #### header sections with multi-paragraph prose to a numbered ordered list. Your explanatory language is preserved in each item (intrusive = "fragile and implicit", the duplicated knowledge example for functional coupling, etc.). Research shows ordered lists convey ordinal relationships more efficiently to LLMs than prose sections with headers. The classic coupling model correspondences are kept as parenthetical anchors: (cf. content/pathological coupling).

• Description — Rewritten from action-oriented ("Use when: designing modular architectures, evaluating coupling...") to reference-oriented ("Domain knowledge reference... Loaded as a dependency by the review and design skills"). The original phrasing overlapped with review and design descriptions, creating potential routing ambiguity in Claude Code's skill selection.

Removed (duplicated content):

• Section 6 ASCII diagram (40 lines) — LLMs process ASCII art as raw text tokens without reconstructing the visual layout. Every element in the diagram (the three dimensions, their sub-items, the balance rule, the key insight) is already stated as prose in Sections 2–4. This is the single largest token savings in the PR.

• Core Principles list (10 lines) — Each of the 8 items restates a point from the body. End-of-document summaries help humans who skim a document; they add zero information for an LLM that has already processed the full context window. The one item with unique framing — "Prior models are incorporated, not replaced" — was moved to Section 2.1 where the classic coupling model references appear.

• Implicit-Explicit Spectrum subsection — Each strength level's definition already describes its implicit/explicit nature (intrusive = "implicit and fragile", contract = "explicit and stable"). The separate subsection restated this as a 4-item summary list. The content is preserved in the new details.md reference file.

Moved (to action skills where it's actually used):

• "Communicating with the User" section — This is behavioral instruction for user-facing interactions ("explain DDD terms in plain language"). It belongs in the review and design skills that actually generate responses to users, not in the knowledge reference document. Added as a constraint in both skills: "Explain DDD terms on first use."

Added:

• 4 worked classification examples after the strength level definitions — Research on LLM taxonomy classification shows that few-shot examples produce 50–70% accuracy gains, particularly at boundary cases (e.g., is shared event schema intrusive or functional coupling?). The examples cover one scenario per strength level with explicit reasoning. This is likely the highest-ROI single change in the PR.

• "Prior models incorporated, not replaced" framing in Section 2.1 — Moved from the deleted Core Principles list. Provides important context that this framework builds on module coupling and connascence rather than replacing them.

balanced-coupling/details.md (new, 45 lines)

Lazy-loaded reference file for content that was split from SKILL.md. This file is not loaded automatically — Claude only reads it during deep analysis when it needs connascence-level granularity or detailed DDD pattern mapping. Zero cost on standard invocations.

Contains:

• Implicit-explicit spectrum elaboration (the 4-level breakdown removed from SKILL.md)
• Connascence degrees — static (name→type→meaning→algorithm→position) and dynamic (execution→timing→value→identity) with ordering
• DDD tactical design connections (aggregate/value object coupling rationale, business logic pattern selection by volatility)
• DDD strategic integration patterns (shared kernel → separate ways mapped to strength and organizational distance)

review/SKILL.md (88 → 91 lines)

• context: fork — The review skill reads extensive codebase contents during analysis. Without fork, all file contents accumulate in the main conversation's context window, compounding the already-heavy skill payload. With fork, the skill runs in an isolated subagent — file contents stay in the subagent's context, and only the final review returns to the main conversation. AskUserQuestion still works in forked context.

• Sharpened description — First sentence now reads "Analyzes an existing codebase for modularity imbalances..." with explicit disambiguation: "use the design skill to create architectures from requirements instead." This prevents routing confusion when a user prompt matches both skills.

• DDD communication constraint — Added from the moved "Communicating with the User" section: explain core/supporting/generic subdomains in plain language on first use.

• HTML output now conditional — Step 4 aligned with the document skill change (see below).

design/SKILL.md (247 → 237 lines)

• context: fork — Same reasoning as review. The design skill reads requirements files and writes multiple output documents.

• Sharpened description — First sentence now reads "Designs modular architecture from a functional requirements document..." with disambiguation toward review for existing codebases.

• Compacted AskUserQuestion tables — Three 3-column markdown tables (~200 tokens) described AskUserQuestion tool call parameters (Header, Question, Options). Replaced with compact inline format: Header: "Approval", Options: "Approved — Proceed to design documents", .... LLMs don't need tabular format to understand tool call parameters — the inline format conveys identical information.

• File verification step — Added after Step 5: "verify all expected output files exist and are non-empty." The design skill writes architecture documents, module designs, and test specs across multiple directories — a verification step catches silent write failures.

• DDD communication constraint — Same as review.

document/SKILL.md (153 → 154 lines)

• HTML generation is now optional — Markdown is always generated. HTML is generated only when the user explicitly requests it. When working in Claude Code (the primary use case), HTML rendering isn't used — the review is consumed as Markdown in the terminal. Making HTML optional saves ~500 tokens of template processing instructions and eliminates a redundant file write on every invocation.

---

What was NOT changed

• Section 4 (Balance Rule) including the 2×2 strength×distance table — this is the one place where a table is structurally justified (it represents a Cartesian product relationship, not a list)
• Section 5 (DDD Connections) stays in SKILL.md — only 18 lines, needed on most invocations for volatility assessment. Moving it would save ~250 tokens but add latency from lazy loading on nearly every use
• Distance and Volatility sections — already well-structured, no reformatting needed
• The coupling.dev link table in the document skill — essential for output quality
• The HTML template (assets/template.html) — still available when HTML is requested
• skills: frontmatter on review/design — working dependency mechanism

Testing notes

• context: fork on review/design should be tested to verify that skills: dependency loading works correctly in forked subagent context. If it doesn't, the fix is removing one frontmatter line from each file.
• The worked examples should improve coupling classification accuracy — worth validating on a real codebase review.

[Copilot]

Pull request overview

Reduces Claude Code skill context usage by condensing and restructuring the Balanced Coupling reference and tightening review/design/document skill instructions, while introducing a lazy-loaded extended reference.

Changes:

• Condensed balanced-coupling/SKILL.md and added worked classification examples; moved deep-dive content into a new details.md.
• Added context: fork and clarified routing/constraints in review and design skills.
• Made HTML generation optional in the document skill (Markdown always generated).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
skills/review/SKILL.md	Adds context: fork, clarifies “existing codebase” scope, and aligns output to optional-HTML document behavior.
skills/design/SKILL.md	Adds context: fork, clarifies “requirements doc” scope, compacts AskUserQuestion instructions, and adds output verification step + DDD-term explanation constraint.
skills/document/SKILL.md	Updates contract to always write Markdown and only generate HTML when explicitly requested; adjusts output instructions accordingly.
skills/balanced-coupling/SKILL.md	Condenses foundations, restructures integration strength into an ordered list, adds examples, and references a lazy-loaded extended file.
skills/balanced-coupling/details.md	New on-demand extended reference for implicit/explicit spectrum, connascence degrees, and additional DDD mappings.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The AskUserQuestion instructions here omit the Question: field (only Header: and Options: are provided). Elsewhere in this same skill you explicitly include Question: (e.g., in the Input section), and the tool call typically requires it; without it, implementations may reject the call or produce a low-quality prompt. Add a clear Question: string for this prompt (and the other condensed prompts below).

[Copilot]

This AskUserQuestion instruction is missing an explicit Question: field. To keep tool calls consistent and avoid schema/tooling failures, include a concrete question string (as done elsewhere in this file).

Suggested change

	Validate using `AskUserQuestion` — Header: "Approval", Options: "Approved — Proceed to design documents", "Needs changes — I'll explain what to adjust", "Rethink — Let's reconsider the module boundaries".
	Validate using `AskUserQuestion` — Header: "Approval", Question: "Do you approve this modular architecture so we can proceed to writing the design documents?", Options: "Approved — Proceed to design documents", "Needs changes — I'll explain what to adjust", "Rethink — Let's reconsider the module boundaries".

[Copilot]

This condensed AskUserQuestion instruction omits the Question: field. Add an explicit question so the tool call is well-formed and consistently specifies what the user is approving.

Suggested change

	After writing all module documents, present the complete set using `AskUserQuestion` — Header: "Modules", Options: "Approved — Proceed to test specifications", "Needs changes — I'll explain which modules need work", "Revisit architecture — The documents reveal a boundary problem".
	After writing all module documents, present the complete set using `AskUserQuestion` — Header: "Modules", Question: "Do you approve this complete set of module design documents?", Options: "Approved — Proceed to test specifications", "Needs changes — I'll explain which modules need work", "Revisit architecture — The documents reveal a boundary problem".

[Copilot]

The heading is missing a space after the section number (### 4.2The ...). This reads oddly and can interfere with consistent formatting/TOC generation. Insert a space after 4.2.

Suggested change

	### 4.2The Balance Rule
	### 4.2 The Balance Rule

[Copilot]

The output path is written using nested backticks (`docs/modularity-review/!`date +%Y-%m-%d`/`), which breaks Markdown inline-code formatting and renders ambiguously. Use an escaping approach that preserves the literal text (e.g., a fenced code block or wrapping the whole path in double backticks) so the intended shell substitution syntax is readable.