Skill Ecosystem Design

Skill Ecosystem Design

Designs interconnected skill networks where each skill reinforces and discovers others through reciprocal relationships, layered capabilities, and cross-domain bridges. This skill creates coherent capability clusters that guide agents from foundational concepts to specialized execution patterns, maximizing auto-loading discovery while preventing trigger overlap between related skills.

TL;DR Checklist

• Every skill lists 2–4 reciprocal related-skills (no isolated skills)
• Skills are organized in layers: foundational → tactical → emergency/advanced
• Trigger terms follow two-tier strategy (technical + conversational) with no overlap between siblings
• Cross-domain bridges use adjacent tech bridge terms to connect skill families
• Dependency graph has no circular references; each skill is a stepping stone to the next
• Hierarchy: foundational → tactical → specialized — user journey flows naturally

When to Use

Use this skill when:

• Designing a new set of skills that form a coherent capability cluster (e.g., a full risk management suite)
• Reviewing an existing skill portfolio for orphaned skills with no related-skills connections
• Building cross-domain bridges between unrelated skill families (e.g., connecting CNCF monitoring to application observability)
• Restructuring a large skill repository where trigger overlap causes false-positive activations
• Creating a tiered capability system where agents can progressively load skills along a user journey
• Onboarding new maintainers by providing a visual map of how all skills interconnect

When NOT to Use

Avoid this skill for:

• Designing individual skill content (triggers, workflows, code examples) — use agent-skill-trigger-engineering instead
• Managing versioning or lifecycle of individual SKILL.md files — use coding-skill-lifecycle-management instead
• Configuring runtime routing thresholds or confidence scores — use agent-confidence-based-selector instead
• Creating a single standalone skill with no need for related skill discovery

Core Workflow

1. Map the Capability Domain — Identify the problem space and enumerate all sub-capabilities that agents might need. Group them by abstraction level:

   • Foundational: Concepts everyone needs (e.g., "what is X?", core principles, basic setup)
   • Tactical: Day-to-day operational skills (e.g., specific patterns, common workflows, troubleshooting)
   • Advanced/Emergency: Edge cases and failure modes (e.g., crisis recovery, performance tuning, security hardening)

   Capability Map Template:
   ┌─────────────────────────────────────────────┐
   │ Domain: [name]                              │
   │                                             │
   │ Foundational                                │
   │   ├─ skill-A (core concept)                 │
   │   └─ skill-B (setup & configuration)        │
   │                                             │
   │ Tactical                                    │
   │   ├─ skill-C (common workflow)              │
   │   ├─ skill-D (optimization pattern)         │
   │   └─ skill-E (integration approach)         │
   │                                             │
   │ Advanced/Emergency                          │
   │   ├─ skill-F (troubleshooting methodology)  │
   │   └─ skill-G (crisis recovery procedure)    │
   └─────────────────────────────────────────────┘
   

   Checkpoint: Each capability must map to exactly one skill. If two capabilities overlap significantly, merge them into a single skill or define clear boundary conditions.

2. Define Reciprocal Relationships — For each skill, identify 2–4 related skills that form a natural progression:

   • Layering relationships: Skill B adds a capability on top of Skill A (e.g., stop-loss builds on position-sizing)
   • Sequencing relationships: Use Skill A before Skill B in the typical workflow (e.g., design before implementation)
   • Complementary relationships: Skills address different facets of the same problem (e.g., monitoring + alerting)

   def build_reciprocal_relationships(
       skills: list[dict],
       domain: str
   ) -> dict[str, list[str]]:
       """Build a directed graph of related-skill relationships.
       
       Enforces the 5 Laws of Elegant Defense:
       - Law 1 (Early Exit): Skills with <2 connections get flagged
       - Law 2 (Parse at boundaries): Validate relationship types before adding edges
       - Law 3 (Atomic Predictability): Relationships are immutable once established
       - Law 4 (Fail Fast): Circular dependencies detected and rejected
       - Law 5 (Don't Hide Failures): Relationship gaps logged for human review
       """
       relationships: dict[str, list[str]] = {s["name"]: [] for s in skills}
       
       for i, skill_a in enumerate(skills):
           for skill_b in skills[i+1:]:
               if are_related(skill_a, skill_b, domain):
                   # Reciprocal: A lists B AND B lists A
                       relationships[skill_a["name"]].append(skill_b["name"])
                       relationships[skill_b["name"]].append(skill_a["name"])
       
       return relationships
   
   
   def are_related(skill_a: dict, skill_b: dict, domain: str) -> bool:
       """Determine if two skills form a meaningful relationship."""
       overlap_score = _calculate_trigger_overlap(skill_a, skill_b)
       
       # Must share at least one semantic concept
       if not _share_concept(skill_a, skill_b):
           return False
       
       # Avoid tangential relationships (only loosely adjacent)
       if overlap_score < 0.3:
           return False
   
       # Strong relationships only: layering, sequencing, or complementary
       return (
           is_layering_relationship(skill_a, skill_b)
           or is_sequencing_relationship(skill_a, skill_b)
           or is_complementary_relationship(skill_a, skill_b)
       )
   

   Checkpoint: Every skill must have at least 2 related skills. No skill should be isolated in the graph.

3. Design Trigger Spaces to Prevent Overlap — Each skill's triggers define its "trigger space." Related skills must not compete for the same trigger terms:

   # ❌ BAD — overlapping trigger spaces cause confusion
   # Skill A (position-sizing):
   triggers: position sizing, how much to trade, risk management
   
   # Skill B (stop-loss):
   triggers: stop loss, risk management, position protection
   # Problem: "risk management" appears in BOTH — agent can't decide which skill to load
   
   # ✅ GOOD — differentiated trigger spaces
   # Skill A (position-sizing):
   triggers: position sizing, how much should i trade, capital allocation, 
             kelly criterion, portfolio weighting, risk budgeting
   
   # Skill B (stop-loss):
   triggers: stop loss, trailing stop, exit strategy, stop placement, 
             stop-loss, position protection, emergency stop
   

   Checkpoint: Run a trigger overlap analysis — if two skills share more than 30% of their trigger terms, differentiate them.

4. Build the Dependency Graph — Create a directed acyclic graph (DAG) showing how skills depend on each other. Skills at the bottom are foundational; skills higher up build on them:

   ┌─────────────────────────────────────────────────────────────┐
   │                    Skill Dependency DAG                        │
   │                                                               │
   │   [risk-kill-switches] ← Emergency layer                      │
   │         ↑                                                     │
   │   [risk-stop-loss]     ← Tactical stop management             │
   │         ↑               ↕                                     │
   │   [risk-position-sizing] ← Foundational sizing decision       │
   │         ↑                                                     │
   │   [risk-drawdown-control] ← Portfolio-level coordination      │
   └─────────────────────────────────────────────────────────────┘
   
   User journey: position-sizing → stop-loss → kill-switches
                    ↓               ↓              ↓
               "How much?"     "Where to exit?"  "When to stop all?"
   

   Checkpoint: Verify the graph is acyclic — no skill can depend on itself through a chain. Reference code-philosophy (Law 2: Parse at boundaries) when validating graph integrity.

5. Implement Cross-Domain Bridges — For skills that span multiple domains, use adjacent technology bridge terms in triggers to connect unrelated skill families:

   # Monitoring skill bridges CNCF and application observability domains
   # CNCF trigger space: prometheus, promql, alerting rules
   # Application trigger space: performance monitoring, how do i track app health
   
   # Bridge terms connect both audiences:
   triggers: prometheus, application monitoring, 
             how do i monitor system health, metrics scraping,
             observability pipeline, grafana dashboard
   

   Checkpoint: Cross-domain bridge skills should have at least 2 triggers from each domain they bridge. Verify that neither domain's audience would be confused by the trigger set.

6. Validate the Skill Network — Run structural validation on the complete network:

   def validate_skill_network(skills: list[dict]) -> dict:
       """Validate structural properties of a skill ecosystem."""
       graph = {s["name"]: s.get("related_skills", []) for s in skills}
       
       checks = {}
       
       # Check 1: No isolated nodes (each skill has >= 2 related)
       isolated = [name for name, deps in graph.items() if len(deps) < 2]
       checks["no_isolated_nodes"] = len(isolated) == 0
       if not checks["no_isolated_nodes"]:
           print(f"WARNING: Isolated skills (need related-skills): {isolated}")
       
       # Check 2: Reciprocity — if A lists B, B must list A
       reciprocity_violations = []
       for name, deps in graph.items():
           for dep in deps:
               if dep in graph and name not in graph[dep]:
                   reciprocity_violations.append(f"{name} → {dep} (not reciprocal)")
       checks["full_reciprocity"] = len(reciprocity_violations) == 0
       
       # Check 3: No circular dependencies
       def has_cycle(node, visited, path):
           if node in path:
               return True
           if node in visited:
               return False
           visited.add(node)
           path.add(node)
           for neighbor in graph.get(node, []):
               if has_cycle(neighbor, visited, path):
                   return True
           path.discard(node)
           return False
   
       checks["no_circular_deps"] = not any(
           has_cycle(name, set(), set()) for name in graph
       )
       
       # Check 4: Trigger overlap between siblings < 30%
       def trigger_overlap(name_a, name_b):
           triggers_a = set(skills[0]["triggers"]) if isinstance(skills[0], dict) else set()
           # This would use actual trigger data from the skills index
           return len(triggers_a & triggers_b) / max(len(triggers_a | triggers_b), 1)
       
       overlaps = [
           (n1, n2) for i, n1 in enumerate(graph) 
           for n2 in graph[n1] if trigger_overlap(n1, n2) > 0.3
       ]
       checks["no_trigger_overlap"] = len(overlaps) == 0
   
       # Check 5: Layering — at least foundational and tactical layers exist
       layer_counts = {"foundational": 0, "tactical": 0, "advanced": 0}
       for s in skills:
           layer = s.get("layer", "tactical")
           layer_counts[layer] = layer_counts.get(layer, 0) + 1
       
       checks["has_layering"] = (
           layer_counts.get("foundational", 0) >= 1 
           and layer_counts.get("tactical", 0) >= 2
       )
       
       return {**checks, "reciprocity_violations": reciprocity_violations}
   

   Checkpoint: All five checks must pass. Any violation must be fixed before publishing the skill set.

7. Document the Ecosystem Map — Create a human-readable map showing all skills, their relationships, and the intended user journey:

   ### Risk Management Ecosystem
   
   **User Journey:** "I need to trade safely" → position-sizing → stop-loss → kill-switches
   
   | Skill | Layer | Related To | Bridge Domain |
   |---|---|---|---|
   | `risk-position-sizing` | Foundational | stop-loss, drawdown-control | — |
   | `risk-stop-loss` | Tactical | position-sizing, kill-switches | trading/risk |
   | `risk-kill-switches` | Emergency | stop-loss, drawdown-control | operations |
   | `risk-drawdown-control` | Foundational | position-sizing, kill-switches | portfolio |
   
   Trigger boundaries: Each skill's triggers cover distinct aspects of risk (sizing vs. placement vs. circuit breaking).
   

Ecosystem Design Patterns

Pattern 1: Layered Defense Architecture

Layer skills progressively from foundational to emergency response. This mirrors the defense-in-depth principle and creates natural progression paths for agents.

┌──────────────────────────────────────────────────────┐
│              Layered Defense Model                    │
│                                                       │
│  Layer 3: Emergency (kill-switches, circuit breakers) │
│         ↑   Prevents catastrophic loss                │
│  Layer 2: Tactical (stop-losses, trailing stops)      │
│         ↑   Manages per-position risk                 │
│  Layer 1: Foundational (position-sizing, budgets)     │
│         ↑   Determines how much to allocate           │
│                                                       │
│  User loads foundational → discovers tactical →       │
│  discovers emergency through reciprocal related-skills │
└──────────────────────────────────────────────────────┘

Each layer is independently loadable but gains value when used in sequence. The related-skills field creates the discovery chain: loading Layer 1 reveals Layer 2, which reveals Layer 3.

Pattern 2: Hub-and-Spoke Discovery

A foundational skill serves as a hub that connects to multiple specialized spokes:

                    [fundamental-concept]
                          │
              ┌───────────┼───────────┐
              ↓           ↓           ↓
        [specialized-A] [specialized-B] [specialized-C]
              ↑           ↑           ↑
         (deep dive)  (deep dive)  (deep dive)

The hub skill covers the core concept broadly. Each spoke drills into a specific aspect. Agents load the hub first, then follow related-skills to the spokes based on their specific need.

Pattern 3: Cross-Domain Bridge

Bridge skills use adjacent terminology to serve multiple domain audiences:

┌──────────────┐                    ┌──────────────┐
│ CNCF Domain  │                    │ App Domain   │
│              │   [bridge skill]   │              │
│ - prometheus ◄──────────────────► - observability│
│ - grafana    │    (dual-audit)   │ - tracing     │
│ - kubernetes │    triggers)       │ - metrics     │
└──────────────┘                    └──────────────┘

Bridge triggers include terms from BOTH domains:
triggers: prometheus, observability, how do i monitor systems,
         metrics dashboard, application health, grafana

Trigger Space Differentiation

When designing related skills, their trigger spaces must be differentiated to prevent auto-loading confusion. Use this framework:

Trigger Overlap Scoring

Differentiation Strategy

# BEFORE: Overlapping risk management triggers (BAD)
# Skill A: triggers: risk, position sizing, how do i decide amount
# Skill B: triggers: risk, stop loss, how do i protect capital  
# Problem: "risk" is shared — both match any risk conversation

# AFTER: Differentiated by role in the risk workflow (GOOD)
# Skill A (sizing): 
#   triggers: position sizing, capital allocation, portfolio budgeting,
#             kelly criterion, how much should i trade, risk budgeting
#   # Focus: "how much" decisions

# Skill B (stops):
#   triggers: stop loss, trailing stop, exit strategy, stop placement,
#             stop-loss, position protection, emergency stop
#   # Focus: "where to exit" decisions

Constraints

MUST DO

• Every skill must list 2–4 related skills (no isolated nodes in the graph)
• Relationships must be reciprocal: if A lists B, B must list A
• Trigger spaces for sibling skills must share fewer than 30% of terms
• Organize skills in layers: foundational → tactical → emergency/advanced
• Reference code-philosophy (5 Laws of Elegant Defense) when building the dependency graph
• Validate the network passes all five structural checks before publishing

MUST NOT DO

• List more than 4 related skills — dilutes focus and suggests poor boundary design
• Create circular dependencies in the skill dependency graph
• Use generic trigger terms (single words like "risk", "code", "data") that cause false positives across domains
• Design skills that exist solely as stepping stones without independent utility — each skill must be loadable and useful standalone
• Hide relationship gaps — if a skill has no natural related skills, note it explicitly rather than fabricating weak connections

Output Template

When designing a skill ecosystem, produce:

1. Capability Map — Enumerated list of all capabilities grouped by layer (foundational/tactical/advanced)
2. Reciprocal Relationship Matrix — Table showing which skills reference each other and the relationship type (layering, sequencing, complementary)
3. Trigger Space Analysis — Overlap matrix showing shared triggers between related skills with percentage calculations
4. Dependency DAG — ASCII flow diagram of the skill dependency graph with no circular references
5. Cross-Domain Bridges — List of bridge skills and the domains they connect, with trigger breakdown by domain
6. Network Validation Report — Results from all five structural checks (no isolated nodes, full reciprocity, no cycles, no trigger overlap, has layering)

Related Skills

Live References

Authoritative documentation links for this domain. The model follows markdown links at load time to resolve external references and inline content.

• Graph Theory Fundamentals (Wikipedia) — Foundational concepts in graph theory applicable to skill dependency graphs
• Dependency Injection Patterns (Martin Fowler) — Fowler's analysis of dependency injection and component relationship patterns
• Network Topology Design Patterns — Research on designing interconnected systems with optimal discoverability and resilience
• Component-Based Architecture (IBM) — IBM's patterns for building component ecosystems with clear interfaces and relationships
• Knowledge Graph Design Patterns — W3C knowledge graph standards applicable to skill relationship networks