tenngoxars/skill-synergy

Skill Synergy — arbitration rules

One authority for which skill wins when several fire. Read this when two or more skills plausibly apply to the current task.

Usage note: this skill is the detailed ruleset. A concise charter (recommended for always-on setups) lives in the repo root as AGENTS.md.template; copy it into AGENTS.md so the core rule loads on every session. This skill is the on-demand reference.

The core rule

Workflow skills (what to do) outrank mode skills (how to talk/write) on the same task. The mode skill adapts; the workflow skill is never weakened.

Everything below is an application of this rule. If a specific case isn't listed, apply the core rule and say so.

Workflow-vs-workflow arbitration

Two or more workflow skills can both plausibly match the same task. Choose by this ladder, in order:

1. Explicit intent wins. If the user named the task type (review, test, design, plan...), the skill for that type leads. No deliberation.
2. Scope decides. A single change (one diff, one function, one file) takes the lighter, cheaper skill; a cross-cutting change (architecture, multi-file refactor, new system) takes the deeper skill.
3. Lifecycle order. Planning → building → verifying is the default sequence. When skills are phases of one effort (design, then implement, then review), run them in that order instead of picking one.
4. Compose over choose. If two skills are sequential phases, run both in order and state the order explicitly ("tdd first, then review").
5. Still ambiguous? Ask. Give a one-line recommendation and let the user pick. Never silently pick a workflow skill — the wrong one wastes a whole task, not a reply.

Skill taxonomy

Classify every installed skill before arbitrating:

• Workflow skills — dictate what gets done: review, test, design, research, writing, refactoring, planning. They produce deliverables.
• Mode skills — dictate how the agent sounds or how much it writes: compression, verbosity, style, brevity. They produce nothing on their own.
• Router skills — pick which workflow to run (optional). They should never be overridden by a mode skill.

If a mode skill would alter a workflow skill's deliverable (report, doc, commit message, PR body), the mode skill yields. If a workflow skill and a mode skill both fire and the workflow skill's output is the deliverable, the mode skill yields.

This charter outranks skill self-descriptions. A skill's frontmatter may claim auto-trigger on a broad phrase (e.g. "auto-triggers on review"). Such claims are superseded here: routing follows this charter's disambiguation, not the skill's own trigger claim. If a skill claims a trigger this charter assigns elsewhere, the charter wins.

Priority matrix (fill in your own skills)

Replace the example skill names below with the skills actually installed in your environment. The rows are ordered by how often the conflict appears in practice.

Task	Leads (workflow)	Yields	Behavior
UI design / polish / visual critique	e.g. your design skill	e.g. your minimal-code skill	Design leads; minimal-code at reduced strength (no bloat, but no YAGNI veto on design craft)
Deep code review (standards + spec)	e.g. your full-review skill	e.g. your compression skill	Full report in normal prose; compression off unless user asks for terse feedback
Over-engineering audit	e.g. your delete-focused review	e.g. your full-review skill	One-axis, deletion-focused pass; skip the full report
Quick terse PR feedback	e.g. your terse-comment skill	—	Only when the user explicitly asked for compressed comments
Stress-test a plan / idea	e.g. your interview/grill skill	e.g. your compression skill	Interview in normal prose; compressed grilling loses its depth
Test-first feature build	e.g. your TDD skill + your minimal-code skill	—	Combo: tests are validation, never cut; minimal impl that passes red-green
Module / API design	e.g. your design-docs skill	e.g. your minimal-code skill	Design phase: depth wins. Implementation phase: minimal-code ladder applies
Writing / editing / teaching	e.g. your writing skill	e.g. your compression skill	Full expression required; compression off
Research / docs capture	e.g. your research skill	e.g. your compression skill	Output files are deliverables; compression only affects chat, never file content
Any coding task, no other skill fired	e.g. your minimal-code skill	e.g. your compression skill	Minimal-code at full strength; compression on-demand only (its per-turn input cost often outweighs savings on code-heavy work)

Trigger disambiguation

When several skills share a trigger word, route by intent, not by which skill matched first:

• "review this" → full review by default. The delete-focused review only if the user says "over-engineered" / "too much code". The terse-comment review only if the user asks for compressed feedback.
• "grill" / "interview me" → the stateful variant (leaves a doc trail) when a codebase exists; the stateless variant when standalone; the batch variant when the user wants all questions at once.
• "handoff" → the document-writing variant by default; the spawn-background-agent variant only when the user wants an immediate background agent.
• "make a plan/spec/tickets" → route by artifact type: spec, tickets, PRD, issues, questionnaire.

Mode-skill discipline

1. A mode skill never silences a workflow skill's deliverable. It may compress chat prose only. Reports, files, commit messages, and PR bodies written by workflow skills stay full.
2. The minimal-code skill's validation line has three tiers: (1) Real validation stays: input validation, error handling for external dependencies, security, accessibility — never cut. (2) Speculative defense is in scope: checks that can't fire, defensive wrappers for "what if" — cut them, that's the minimal-code skill's job. (3) Tests and task docs follow the user's explicit requirements: the minimal-code skill never uses YAGNI to cut tests or docs the user requires — but redundancy inside tests, over-mocking, and bloat in docs are still fair game.
3. Two mode skills firing together (compression + minimal-code): minimal-code governs code, compression governs chat — but only if the session is prose-heavy; on code-heavy sessions compression should be off or at reduced strength (net token loss otherwise).
4. Subagents inherit the arbitration. When spawning a subagent for a review or research task, state the mode explicitly in the task: "normal prose" or "compressed output". Never leave it implicit.

Combinations that pay rent

• TDD skill + minimal-code skill — test-first, minimal implementation.
• Full review, then delete-focused review on the same diff — full pass, then a deletion pass.
• Interview skill + memory-compression skill — compress accumulated session notes after the interview.
• Terse commit-message skill after any workflow skill finishes — always safe.
• Router skill for flow routing, this skill for mode arbitration — the router picks the road, synergy picks the gear.

Customizing

This skill is a framework, not a config. To make it yours:

1. Replace every "e.g. your X skill" in the priority matrix with the real skill names in your environment. A filled-in reference using common public skills lives in examples/example-config.md — copy it and substitute your own names instead of filling the template from scratch.
2. Remove rows for task types you never hit.
3. If your environment has a global rules file (AGENTS.md or equivalent), copy the core rule into it so every environment loads it.
4. If a new conflict appears that isn't covered, classify both skills (workflow or mode), apply the core rule, and add a row.