Purpose
Turn a tangle of undocumented inter-team API calls into a scored dependency map that exposes coupling risk, single points of failure, and circular dependencies — then deliver a ranked decoupling roadmap so platform teams can ship independently. Solves the "why does every release require three teams to coordinate" problem before it stalls the roadmap.
When to Use
Invoke this skill when the user asks to:
- Document how services and teams depend on each other's APIs
- Diagnose why releases require cross-team coordination or keep breaking each other
- Identify coupling risks, single points of failure, or circular dependencies before a re-architecture
- Plan how to reduce interdependencies ahead of a team reorg or service split
- Prepare a dependency review for an architecture board or platform planning cycle
- Assess the blast radius of deprecating or versioning a widely consumed API
Inputs Required
Before starting, collect:
- Services in scope: The APIs/services to map, with owning team for each
- Dependency data: Known calls between services — who calls whom, and roughly for what (list, table, or diagram description)
- Team boundaries: Which teams own which services, and how they release (independent, coordinated, monorepo, etc.)
- Criticality signals: Which services are on the critical path for revenue or core user flows
- Contract state: Whether APIs have versioned contracts, schemas (OpenAPI/gRPC/etc.), or are informal
- Known pain points: Where cross-team coordination, breakage, or "we can't change X" already hurts
- Change goal: What triggered this — reorg, re-architecture, incident, or reliability push
If criticality or contract state is missing, infer conservatively from the dependency data and flag every assumption in the output.
Instructions
Step 1: Build the Dependency Inventory
Normalize the raw dependency data into a consistent edge list. For each dependency, capture:
- Consumer: The service/team making the call
- Provider: The service/team being called
- Direction & type: Synchronous (blocking request/response), asynchronous (event/queue), or shared-data (database/cache coupling)
- Purpose: One phrase describing what the consumer needs
- Contract: Versioned schema / informal / undocumented
Deduplicate and confirm each edge has both a consumer and a provider. Flag any dependency the user described that couldn't be resolved to two named services.
Step 2: Score Coupling Risk per Dependency
Assign each dependency a coupling risk score (Low / Medium / High / Critical) based on:
- Synchronicity: Synchronous blocking calls score higher than async — a slow provider stalls the consumer
- Contract maturity: Undocumented or unversioned contracts score higher — any change risks silent breakage
- Criticality: Dependencies on the revenue/core-flow critical path score higher
- Team distance: Cross-team dependencies score higher than intra-team — coordination cost and release friction
- Fan-out: Providers consumed by many teams score higher — large blast radius on change
Escalate to Critical when a dependency is synchronous, undocumented, cross-team, and on the critical path.
Step 3: Detect Structural Problems
Analyze the graph for the failure patterns that cause the most pain:
- Single points of failure: Providers whose outage would cascade to many consumers — rank by number of downstream services and their criticality
- Circular dependencies: Cycles where A → B → A (directly or transitively) — these make independent deployment impossible; name every cycle explicitly
- Chatty coupling: Consumer/provider pairs with many distinct synchronous dependencies — candidates for consolidation or an aggregation layer
- Hidden shared-data coupling: Two services writing/reading the same database or cache — the most brittle coupling because it bypasses any contract
- God services: A single provider that everyone depends on — a bottleneck for both reliability and org velocity
Step 4: Identify Decoupling Opportunities
For each significant coupling risk, propose the strongest applicable pattern:
- Contract-first + versioning: Introduce a versioned schema and backward-compatible change policy so providers can evolve without breaking consumers
- Sync → async: Replace a blocking call with an event or queue where the consumer doesn't need an immediate response
- Anti-corruption layer / API gateway: Insulate consumers from a volatile or shared provider
- Data ownership split: End shared-database coupling by giving each service its own store and an explicit API
- Consolidation: Merge chatty endpoints into a single coarser-grained call
- Ownership realignment: Where a dependency crosses a team boundary that shouldn't exist, note the reorg move that removes it
Step 5: Rank the Decoupling Roadmap
Order recommended actions by impact-to-effort. For each action list:
- What to change — the specific dependency or structural problem addressed
- Pattern applied — from Step 4
- Impact — coordination cost removed, blast radius reduced, or SPOF eliminated
- Effort — S / M / L with the main cost driver
- Sequencing note — anything that must happen first (e.g., "version the contract before splitting ownership")
Lead with actions that break circular dependencies or eliminate critical-path SPOFs — these unlock independent delivery fastest.
Step 6: Summarize the Coupling Health Verdict
Give a one-paragraph verdict: how coupled is this system, what's the single biggest risk, and what's the first move. Be direct.
Output Format
- Structure: Dependency inventory as a table; risk scoring, structural problems, and roadmap as labeled sections; roadmap as a ranked list
- Length: 1,000–1,400 words
- Format: Structured document — inventory and roadmap in tables/ranked lists, analysis in tight prose
- Sections: Dependency Inventory → Coupling Risk Scores → Structural Problems (SPOFs / Cycles / Shared-Data / Chatty / God Services) → Decoupling Opportunities → Ranked Decoupling Roadmap → Coupling Health Verdict
- Tone: Platform architect — precise, risk-first, opinionated about sequencing; no hedging on the biggest problem
Quality Checklist
Before delivering output, verify:
- [ ] Every dependency in the inventory has a named consumer, named provider, direction/type, and contract state
- [ ] Every dependency carries a coupling risk score with a stated reason — not a bare label
- [ ] All circular dependencies are named explicitly, or the output states none were found
- [ ] Single points of failure are ranked by downstream count and criticality — not listed arbitrarily
- [ ] Every roadmap item names a specific decoupling pattern, an impact, an effort rating, and a sequencing note
- [ ] Every inferred criticality or contract-state assumption is flagged for the user to confirm
Notes
- Shared-database coupling is the most common hidden dependency and the one teams most often forget to report — probe for it if the dependency data only mentions API calls
- Circular dependencies are usually the true reason teams can't release independently; prioritize breaking them even when the risk score of any single edge looks moderate
- Sync-to-async is tempting but not free — only recommend it where the consumer genuinely doesn't need the response inline
- If the dependency data is thin, produce the map with what's given and list the specific edges the user should confirm rather than inventing plausible-looking connections
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills