@skill-graph/cli 0.5.6

package/marketplace/skills/context-engineering/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: context-engineering
+description: "Use when designing what information reaches an LLM agent before it reasons — system prompt, persistent memory, always-loaded rules, injected skills, and the user prompt — or when diagnosing why an agent produced a wrong answer despite a clear instruction. Covers the four context failure modes (missing, stale, wrong, overwhelming), the five-layer context stack, four context quality metrics (injection precision and recall, utilization, freshness), the Frequent Intentional Compaction (FIC) protocol, subagent delegation for context-heavy work, and the failure-mode decision tree. Do NOT use for prompt wording (use `prompt-craft`), authoring a new SKILL.md (use `skill-scaffold`), or deciding which skill the router activates for a given query (use `skill-router`)."
+license: MIT
+compatibility: "Provider-agnostic; principles apply across Claude, GPT, Gemini, and open-weight models. Layer mapping varies by harness (Claude Code, OpenCode, Cursor, Continue, Aider) but the five-layer abstraction holds."
+allowed-tools: Read Grep Bash Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/context\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"context engineering\\\\\\\",\\\\\\\"context failure\\\\\\\",\\\\\\\"agent context\\\\\\\",\\\\\\\"context quality\\\\\\\",\\\\\\\"context design\\\\\\\",\\\\\\\"missing context\\\\\\\",\\\\\\\"stale context\\\\\\\",\\\\\\\"wrong context\\\\\\\",\\\\\\\"overwhelming context\\\\\\\",\\\\\\\"context window\\\\\\\",\\\\\\\"context utilization\\\\\\\",\\\\\\\"injection precision\\\\\\\",\\\\\\\"injection recall\\\\\\\",\\\\\\\"frequent intentional compaction\\\\\\\",\\\\\\\"FIC\\\\\\\",\\\\\\\"context compaction\\\\\\\",\\\\\\\"subagent delegation\\\\\\\",\\\\\\\"context stack\\\\\\\",\\\\\\\"context layers\\\\\\\",\\\\\\\"skill injection\\\\\\\",\\\\\\\"context engineering stack\\\\\\\",\\\\\\\"agent failure diagnosis\\\\\\\",\\\\\\\"why did the agent fail\\\\\\\"]\",\"examples\":\"[\\\\\\\"the agent ignored the instruction and used the wrong query helper — was the right skill loaded?\\\\\\\",\\\\\\\"we keep getting generic answers from the agent even though the skill has the answer — what's wrong?\\\\\\\",\\\\\\\"I want to design which skills get injected for which prompts — where do I start?\\\\\\\",\\\\\\\"the agent's quality drops in long sessions — when should I compact?\\\\\\\",\\\\\\\"diagnose this agent failure: it had the file open but produced wrong output anyway\\\\\\\",\\\\\\\"we have 200 skills and the agent picks the wrong ones — fix the injection\\\\\\\",\\\\\\\"should I read this 5K-line file directly or delegate to a subagent?\\\\\\\",\\\\\\\"audit our context pipeline — what's loaded when, and is any of it stale?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"improve this prompt's wording to get better outputs\\\\\\\",\\\\\\\"scaffold a new SKILL.md for our team's deploy procedure\\\\\\\",\\\\\\\"the router picked the wrong skill for this query — debug it\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\",\\\\\\\"write a doc explaining our agent system to a new joiner\\\\\\\",\\\\\\\"investigate why production crashed at 3am\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-craft writes the wording of one instruction; context-engineering shapes the entire surrounding payload (rules, memory, skills, file reads) that the prompt sits inside\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-scaffold\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-scaffold authors the structure of a single SKILL.md file; context-engineering decides which skills should exist, get loaded, and reach the model in the first place\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-router\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-router is the runtime mechanism that selects skills for a query; context-engineering is the design discipline behind the entire context stack the router operates within\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"skill-router\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/context-engineering/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/context-engineering/SKILL.md
+---
+
+# Context Engineering
+
+## Coverage
+
+- Core principle: the model is a reasoning engine that reasons over whatever is in its context window — wrong context produces correct reasoning over false premises
+- The five-layer context stack: system prompt, persistent memory, always-loaded rules, injected skills, agent prompt — what each layer does and how each can fail
+- The four context failure modes: missing, stale, wrong, overwhelming — diagnostic questions for each, table of symptoms, and prevention strategies
+- Four context quality metrics: injection precision, injection recall, context utilization, freshness score — definitions, healthy ranges, and how to measure each
+- Frequent Intentional Compaction (FIC): proactive compaction at task boundaries, target utilization range, and the difference between planned and forced compaction
+- Subagent delegation pattern: when to delegate context-heavy investigation to a subagent so the main agent receives a summary instead of raw evidence
+- Debugging decision tree: how to diagnose any agent failure by walking from missing-context through overwhelming-context before blaming the model
+- The verification checklist: gates a context-engineering review must pass before declaring the pipeline healthy
+
+## Philosophy
+
+The model is a reasoning engine that reasons over whatever is in its context window. If the context is wrong, the reasoning is correct but the conclusion is wrong. This means most agent failures are context failures, not model failures.
+
+Without this discipline, teams blame the model for mistakes caused by missing keywords, stale skill content, or an overwhelmed window. Context engineering provides the diagnostic framework to identify *why* an agent produced a wrong answer and the design principles to prevent recurrence. It treats the context window as a deliberate design surface — not a dumping ground — so that the model's native reasoning produces the correct output without heroic prompting.
+
+> Most agent failures are context failures, not model failures. Context engineering is the discipline of designing what information the model sees, when it sees it, and in what form — so that the model's native reasoning produces the correct output without heroic prompting.
+
+## Core Principle
+
+The model is a reasoning engine. It reasons over whatever context is in its window. If the context is wrong, the reasoning is correct but the conclusion is wrong. **You cannot prompt your way out of a context problem.**
+
+Three implications:
+
+1. **Garbage in, garbage out** — a perfectly written prompt cannot compensate for missing domain knowledge. The model will hallucinate confidently.
+2. **Signal-to-noise ratio matters** — flooding the context window with irrelevant information degrades performance just as surely as omitting critical information. The model attends to everything.
+3. **Context is a design surface** — the information in the context window is as intentional as a database schema or an API contract. It should be designed, measured, and iterated.
+
+## The Five-Layer Context Stack
+
+```
+Layer 5 — Agent prompt          (the task-specific instruction from user or orchestrator)
+Layer 4 — Injected skills       (domain knowledge selected per task by a router or injector)
+Layer 3 — Always-loaded rules   (universal guardrails: security, naming, GDPR, etc.)
+Layer 2 — Persistent memory     (cross-session knowledge: user preferences, prior decisions)
+Layer 1 — System prompt         (foundational identity, non-negotiable rules, reading order)
+```
+
+Each layer adds context. Each layer can introduce failure. The context engineer's job is to ensure the right information reaches the right layer at the right time.
+
+| Layer | Loaded when | Failure mode if broken |
+|-------|-------------|-----------------------|
+| Layer 1 — System prompt | Always (turn 0) | Agent ignores fundamental rules and identity |
+| Layer 2 — Persistent memory | Always (auto-loaded at session start) | Agent repeats prior mistakes or ignores user preferences |
+| Layer 3 — Always-loaded rules | Always (auto-loaded by harness) | Agent violates universal guardrails |
+| Layer 4 — Injected skills | Per task, via router or keyword match | Agent lacks domain knowledge for the task |
+| Layer 5 — Agent prompt | Per request | Agent operates on an ambiguous or underspecified instruction |
+
+The exact mechanism varies by harness — Claude Code uses `CLAUDE.md` + `.claude/rules/` + `MEMORY.md`; Cursor uses `.cursorrules`; OpenCode uses `AGENTS.md`; Aider uses `CONVENTIONS.md`. The abstraction holds across all of them.
+
+## The Four Context Failure Modes
+
+Every agent mistake can be traced to one of four context failures. Diagnosing which failure mode caused the mistake is the first step to fixing it.
+
+### Missing Context
+
+The agent does not have the information it needs. Most common, easiest to diagnose.
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Agent uses wrong API or helper despite a skill that names the correct one | Skill not injected for this prompt's keywords | Add task-phrase keywords to the skill; verify routing |
+| Agent ignores a project convention (naming, structure, format) | Convention not in always-loaded rules | Promote the rule from skill to always-loaded layer |
+| Agent contradicts a decision made in a prior session | Decision not in persistent memory | Save the decision to a memory topic file |
+| Agent uses a deprecated pattern | Skill content does not name the current replacement | Update the skill with the current pattern + deprecation note |
+
+**Diagnostic question:** "Did the agent have access to the information that would have prevented this mistake?"
+
+### Stale Context
+
+The agent has the information, but it is outdated. The skill says X, but the codebase has moved to Y.
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Agent references a file that was renamed several sessions ago | Skill references not updated after the rename | Run drift check; update file paths in the skill |
+| Agent uses an old version of an external API | Skill content not refreshed after the upstream change | Update the skill, bump `freshness`, link new docs |
+| Agent applies a pattern that was superseded by a recorded decision | The supersession is not cross-referenced from the skill | Add a "superseded by" pointer in the skill body |
+| Memory says "blocked by X" but X was resolved last week | Memory topic file not pruned | Update or remove the stale memory entry |
+
+**Diagnostic question:** "Was this information correct when it was written? Has the source of truth changed since?"
+
+**Prevention:** every skill carries a `drift_check.last_verified` date. Skills whose verification is older than the lifecycle policy (e.g. 90 days for portable, 30 days for integration skills) should be reviewed before use in a high-stakes task.
+
+### Wrong Context
+
+The agent has information, but it is incorrect. The most dangerous failure mode because the agent acts confidently on false premises.
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Agent applies a pattern from a different project / different library version | Skill content was copied without adapting | Audit skill for cross-project accuracy; add scope qualifier |
+| Agent follows a rule that contradicts another rule | Two rules conflict without precedence | Establish explicit precedence or merge the rules |
+| Agent uses a formula with incorrect semantics | Formula in skill has a bug | Verify formulas against actual implementation code, with a line-number citation |
+| Agent cites a reference that says the opposite of what the skill claims | Hallucinated or misquoted reference | Add source attribution with file path and line numbers |
+
+**Diagnostic question:** "Was the information the agent acted on actually correct?"
+
+**Prevention:** skill content cites specific files and line numbers. Generic "best practice" advice without grounded evidence is a wrong-context risk.
+
+### Overwhelming Context
+
+The agent has too much information. The signal is diluted by noise; the model's attention is spread too thin.
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Agent ignores a critical rule buried in a 2000-line skill | Skill is a monolith without internal structure | Split into thin SKILL.md + `references/` for depth |
+| Agent produces generic output despite specific guidance | Too many skills injected, none deeply read | Improve injection precision; remove overly broad keywords |
+| Agent's work quality degrades in the second half of a long session | Context window approaching capacity | Apply FIC at task breakpoints |
+| Agent follows a less-relevant rule over a more-relevant one | Rules not prioritised by specificity | Use always-loaded rules for universal guardrails; skills for domain-specific |
+
+**Diagnostic question:** "Did the agent have so much context that it couldn't focus on the right information?"
+
+**Prevention:** measure injection precision. If more than 30% of injected skills are irrelevant to the task, the injection system needs tuning.
+
+## Context Quality Metrics
+
+Four metrics measure the health of a context engineering system. Track these over time to identify systemic issues.
+
+### Injection Precision
+
+Of all skills injected for a task, what percentage were actually needed?
+
+```
+Injection Precision = (skills used / skills injected) × 100
+```
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| > 80% | Healthy | Maintain |
+| 50–80% | Noisy | Tighten keywords; remove overly broad trigger phrases |
+| < 50% | Broken | Audit keywords; too many skills match too many prompts |
+
+**How to measure:** after completing a task, review which injected skills were actually referenced in the agent's work. Skills injected but never consulted are false positives.
+
+### Injection Recall
+
+Of all skills that would have been useful for a task, what percentage were actually injected?
+
+```
+Injection Recall = (relevant skills injected / relevant skills total) × 100
+```
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| > 90% | Healthy | Maintain |
+| 70–90% | Gaps exist | Add missing keywords to under-matched skills |
+| < 70% | Systematic failure | Review skill descriptions; add trigger phrases |
+
+**How to measure:** after a context failure, check whether the skill that would have prevented it was indexed and whether its keywords matched the prompt.
+
+### Context Utilization
+
+What percentage of the context window is used productively (contributes to correct output)?
+
+```
+Context Utilization = (productive context / total context used) × 100
+```
+
+Productive context: relevant skill content, necessary file reads, on-topic conversation history. Unproductive context: irrelevant skills, stale memory, redundant file reads, verbose tool output.
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| > 70% | Efficient | Maintain |
+| 40–70% | Acceptable but improvable | Compact stale conversation; reduce verbose tool output |
+| < 40% | Wasteful | Apply FIC; review what loads at startup |
+
+### Freshness Score
+
+What percentage of injected skill content is current (drift_check within the lifecycle window)?
+
+```
+Freshness Score = (skills with drift_check inside window / total injected skills) × 100
+```
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| > 90% | Current | Maintain |
+| 70–90% | Drifting | Schedule drift check for stale skills |
+| < 70% | Dangerous | Stop; audit all stale skills before continuing |
+
+## Frequent Intentional Compaction (FIC)
+
+FIC is a proactive context-management strategy. Instead of waiting for the window to fill and reacting with an emergency compact, plan compaction points into the workflow.
+
+**Target utilization:** 40–60% of the context window during steady-state work.
+
+**When to compact:** at natural breakpoints, not when forced by pressure.
+
+| Breakpoint | Action |
+|-----------|--------|
+| Task boundary (one task done, before starting next) | Compact — summarise what was accomplished, discard working details |
+| Research complete, implementation starting | Compact — keep conclusions, discard search results and exploration |
+| After reading a large file or running an enumeration | Summarise key findings; do not keep raw output in conversation |
+| After a debugging session | Keep the fix and the root cause; discard the investigation steps |
+
+The forced compact is dangerous because it is uncontrolled — you lose whatever the compaction algorithm decides is least important, which may include critical task context.
+
+### FIC Anti-Patterns
+
+| Anti-pattern | Why it fails | Fix |
+|-------------|-------------|-----|
+| Never compacting ("I might need that later") | Window fills; forced compact loses more than planned compact would | Compact proactively at breakpoints |
+| Compacting too aggressively ("keep only the plan") | Loses critical decisions and constraints | Keep decisions, constraints, and the active plan; discard exploration |
+| Reading entire large files "just in case" | Wastes 5–10K tokens per file | Read targeted sections; use grep to find relevant lines |
+| Keeping full tool output in context | JSON or log output is enormous and rarely re-used | Summarise tool results immediately after reading |
+
+## Subagent Delegation for Context-Heavy Work
+
+Some tasks consume enormous context (reading 20 files, searching across the codebase, analysing dependencies). Doing this in the main session pollutes its context for every subsequent step. Delegate to a subagent instead:
+
+```
+Main agent:    "I need to understand the data pipeline that feeds the dashboard"
+                ↓ spawn subagent with narrow scope
+Subagent:      reads 15 files, traces the pipeline, builds a mental model
+                ↓ returns a 200-word structured summary
+Main agent:    receives summary (≈200 tokens, not ≈15,000)
+```
+
+The subagent's context is disposable. The main agent gets the conclusion without the investigation cost.
+
+This pattern is especially valuable for: codebase exploration, audit work, dependency tracing, multi-file refactor planning, and any "look at everything before deciding" investigation.
+
+## Debugging Agent Failures
+
+When an agent produces wrong output, walk this decision tree before blaming the model:
+
+```
+Agent produced wrong output
+    │
+    ▼
+Was the right skill (or rule) loaded?
+    │
+   NO ──▶  MISSING CONTEXT
+    │       Fix: add keywords; promote rule to always-loaded layer; save the decision
+    │
+   YES
+    │
+    ▼
+Was the loaded content correct and current?
+    │
+   NO ──▶  STALE or WRONG CONTEXT
+    │       Fix: update the skill; verify against source; cite line numbers
+    │
+   YES
+    │
+    ▼
+Was the context window > 80% full?
+    │
+   YES ──▶ OVERWHELMING CONTEXT
+    │       Fix: apply FIC; delegate investigation to a subagent
+    │
+   NO
+    │
+    ▼
+Was the prompt itself ambiguous or underspecified?
+    │
+   YES ──▶ Prompt problem (use prompt-craft)
+    │
+   NO
+    │
+    ▼
+Genuine model reasoning failure (rare; try a different model or add chain-of-thought)
+```
+
+### Failure analysis template
+
+When recording a context failure for retrospective:
+
+```markdown
+## Context Failure Report
+
+Date:            YYYY-MM-DD
+Task:            [what the agent was asked to do]
+Failure:         [what went wrong]
+Failure mode:    Missing | Stale | Wrong | Overwhelming
+Root cause:      [why the context was bad]
+Fix applied:     [what was changed to prevent recurrence]
+Layer affected:  Layer 1 / 2 / 3 / 4 / 5 (system prompt / memory / rules / skills / prompt)
+```
+
+## Verification
+
+Use this checklist when designing a new skill, debugging a failure, or auditing the context pipeline:
+
+- [ ] Every agent failure was diagnosed to one of the four failure modes (Missing, Stale, Wrong, Overwhelming) before any fix landed
+- [ ] Skills involved in any failure now have keywords that match how users actually phrased the request
+- [ ] Skill content cites specific files and line numbers, not generic advice
+- [ ] `drift_check.last_verified` is inside the lifecycle window for every active skill
+- [ ] No two skills give contradictory advice on the same topic (`relations.boundary` is honest about ownership)
+- [ ] Context utilization is tracked at task breakpoints; FIC fires at natural boundaries
+- [ ] Injection precision is above 80% (most injected skills are actually consulted)
+- [ ] Injection recall is above 90% (most needed skills are injected)
+- [ ] Context-heavy investigations are delegated to subagents so the main agent receives summaries, not raw evidence
+- [ ] Always-loaded rules contain only universal guardrails; domain-specific guidance lives in skills
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `prompt-craft` | The fix is in the wording of one instruction (clarity, format, few-shot examples), not the surrounding stack |
+| `skill-scaffold` | Authoring or restructuring a single SKILL.md file (the contract, not the system around it) |
+| `skill-router` | Debugging which skill the router activates for a specific query — that is a routing-mechanism question, not a context-design question |
+| `code-review` | Reviewing AI-generated code for correctness, security, or style |
+| `documentation` | Writing prose for a human reader about how the agent system works |
+| `debugging` | Investigating a runtime production failure that is not specifically an agent context failure |

package/marketplace/skills/context-graph/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: context-graph
+description: "Use when designing or auditing the multi-graph context architecture of an AI-coding workspace: skill graph, document routing graph, memory index, script registry, and the cross-graph edges between them. Covers edge typing, orphan detection, connectivity health, deterministic graph synthesis signals, change-propagation checks, and drift or hub-and-spoke anti-patterns. Do NOT use for authoring one SKILL.md (use `skill-scaffold`), validating one skill (use `graph-audit`), live routing decisions (use `skill-router`), context-window budgeting (use `context-window`), or session load/drop choices (use `context-management`)."
+license: MIT
+compatibility: "Architecture-level skill. Applies to any agent-coding workspace that has more than one skill / doc-routing / memory artifact and any way to traverse them — Claude Code, OpenCode, Cursor, Aider, Continue, Copilot Workspace, or a custom harness. The four-graph model and the orphan / connectivity metrics are independent of the specific runtime."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/context\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-13\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{\\\\\\\"SKILL_GRAPH.md\\\\\\\":\\\\\\\"a63fc59a1d99933fc6bc5c4033f8be86ee2f5460f3b5d5ab232a3f77eff71c8f\\\\\\\",\\\\\\\"docs/PRIMER.md\\\\\\\":\\\\\\\"e6bd99468c224fe4c9606e147c5db94dff889feeb9ca5d80084480039c7e9296\\\\\\\",\\\\\\\"docs/concept-map.md\\\\\\\":\\\\\\\"053e5cf891d7abf7efb30c9014fd2365da7d13588ef6b55057520756a315dc8c\\\\\\\",\\\\\\\"docs/diagrams/starter-graph.mmd\\\\\\\":\\\\\\\"6aeaa417e08efbb6bb90b34f56c8df7f06dc608e3c8cd743d428da9fcfaf278c\\\\\\\",\\\\\\\"scripts/generate-manifest.js\\\\\\\":\\\\\\\"9d7bbbdae440fdb1763d61ffa7bda10c9efae92359d1c2139d0e971582d59e0e\\\\\\\",\\\\\\\"scripts/skill-overlap.js\\\\\\\":\\\\\\\"ed642cbc677cc76ec1321300b37d6752337b6b5541c7a9f558fd315d6f934e4b\\\\\\\"}}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"context graph architecture\\\\\\\",\\\\\\\"multi-graph context model\\\\\\\",\\\\\\\"skill knowledge graph\\\\\\\",\\\\\\\"document routing graph\\\\\\\",\\\\\\\"memory index graph\\\\\\\",\\\\\\\"script command registry graph\\\\\\\",\\\\\\\"cross-graph edges\\\\\\\",\\\\\\\"orphan detection skill graph\\\\\\\",\\\\\\\"graph connectivity metrics\\\\\\\",\\\\\\\"average node degree\\\\\\\",\\\\\\\"hub-and-spoke anti-pattern\\\\\\\",\\\\\\\"reciprocal relations\\\\\\\",\\\\\\\"bidirectional graph edges\\\\\\\",\\\\\\\"change propagation across graphs\\\\\\\",\\\\\\\"edge type taxonomy\\\\\\\",\\\\\\\"adjacent boundary verify_with\\\\\\\",\\\\\\\"deterministic graph synthesis\\\\\\\",\\\\\\\"bundle co-membership\\\\\\\"]\",\"examples\":\"[\\\\\\\"we have ~300 skills but the agent never finds half of them — what's the diagnostic frame?\\\\\\\",\\\\\\\"how do I measure whether our skill graph is actually navigable vs just present?\\\\\\\",\\\\\\\"I changed a webhook handler — what's the discipline for tracing the impact across docs, skills, memory, and scripts?\\\\\\\",\\\\\\\"we keep accumulating orphan skills and our connectivity drops every quarter — how do I make graph-health a deliberate gate?\\\\\\\",\\\\\\\"the agent is loading 15 skills per task and burning context — is the underlying graph too dense, too sparse, or wrong-shaped?\\\\\\\",\\\\\\\"design a deterministic recipe for synthesizing the skill graph from frontmatter without running an LLM\\\\\\\",\\\\\\\"what's the right cap on adjacent / boundary / verify_with relations per skill?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"scaffold a new SKILL.md from a template\\\\\\\",\\\\\\\"validate that this single skill's frontmatter matches the schema\\\\\\\",\\\\\\\"decide which skill to inject for this query right now\\\\\\\",\\\\\\\"this skill says 'use orgQuery'; that one says 'never use orgQuery' — fix the conflict\\\\\\\",\\\\\\\"decide what should and shouldn't be in this agent's context window for this task\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-router\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-router is the per-query dispatch decision (which skill activates now); context-graph is the underlying graph the router traverses\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"graph-audit\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"graph-audit validates one skill's schema and relation-target existence; context-graph reasons about the topology of the whole graph (orphans, connectivity, edge cap discipline)\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-infrastructure\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-infrastructure owns the live skill library tooling (census, conflict detection, routing-gap reporting); context-graph owns the architectural model behind it\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-scaffold\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-scaffold authors a single SKILL.md; context-graph designs the graph that those authored skills participate in\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"skill-router\\\\\\\",\\\\\\\"graph-audit\\\\\\\",\\\\\\\"skill-infrastructure\\\\\\\",\\\\\\\"skill-scaffold\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"graph-audit\\\\\\\",\\\\\\\"skill-infrastructure\\\\\\\"]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Skill Graph library topology and context discovery model\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"hybrid\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[\\\\\\\"SKILL_GRAPH.md\\\\\\\",\\\\\\\"docs/PRIMER.md\\\\\\\",\\\\\\\"docs/concept-map.md\\\\\\\",\\\\\\\"docs/diagrams/starter-graph.mmd\\\\\\\",\\\\\\\"scripts/generate-manifest.js\\\\\\\",\\\\\\\"scripts/skill-overlap.js\\\\\\\"],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"inferred_edges_replace_authored_relations\\\\\\\",\\\\\\\"orphan_skills_remain_unreachable\\\\\\\",\\\\\\\"relation_caps_turn_into_hub_and_spoke_graph\\\\\\\",\\\\\\\"change_propagation_ignores_cross_graph_edges\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"repo_code_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/context-graph/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1597\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/context-graph/SKILL.md
+---
+
+# Context Graph
+
+## Coverage
+
+The architectural model behind navigable context in an AI-coding workspace. Names the four interconnected graphs that any mature workspace accumulates — Skill Knowledge Graph, Document Routing Graph, Memory Index, Script / Command Registry — and the cross-graph edges that connect them (skill → script, skill → memory, doc-routing → doc, script → command). Specifies the three skill-graph edge types (`adjacent`, `boundary`, `verify_with`) and their per-edge-type caps. Defines orphan detection (a node with zero or near-zero incoming edges that agents cannot find by traversal) and the priority order for remediation (security skills first, then financial, integration, infrastructure, then UX). Specifies graph-connectivity metrics with healthy / unhealthy bands: connectivity, average degree, orphan rate, max degree, cluster count, hub-spoke ratio. Names the five deterministic signals that should drive graph synthesis (explicit prose references, manual `relations` frontmatter, bundle co-membership, shared routing labels, keyword overlap) — never an LLM at synthesis time. Walks the change-propagation checklist that traces a single edit across all four graphs. Catalogs the anti-patterns that quietly destroy graph quality: edge inflation, one-way edges, optional-metadata mindset, AI-inferred edges that drift on rebuild, ignoring cross-graph edges.
+
+## Philosophy
+
+Without a navigable graph, agents cannot discover context they did not already know existed. The original failure mode looks like this: a skill exists, the agent doesn't reference it by name in the current prompt, and the routing layer has no edge to find it from — so the skill might as well not exist. A workspace can ship hundreds of skills and still operate as if it had ten, because the other 290 are unreachable from any traversal an agent actually performs.
+
+Context discovery is therefore a precondition for context quality. If the right skill, doc, or memory file cannot be found by following edges from the current task, content quality is irrelevant. Graph maintenance — adding edges, fixing orphans, capping inflation, keeping cross-graph references current — is a quality gate, not optional metadata. Every new skill enters the system with a question attached: who reaches this from where, by which edges?
+
+The deterministic-signal discipline is the second non-negotiable. Graph synthesis must be a deterministic function of the authored artifacts (frontmatter relations, bundle membership, prose references, shared routing labels, keyword overlap) — not an LLM inference. If the graph drifts on rebuild, agents lose the one stable surface they have. Use AI to _suggest_ edges during authoring; never to _generate_ the live graph at runtime.
+
+## 1. The Four Context Graphs
+
+A mature AI-coding workspace converges on four interconnected graphs:
+
+### Graph 1 — Skill Knowledge Graph
+
+Nodes are skill files; edges are the typed relations declared in skill frontmatter. The job of this graph is _what knowledge exists in the workspace, and what knowledge teaches alongside what other knowledge_. The graph's vital signs are connectivity (no large isolated components), orphan rate (no skills nobody references), and edge-type discipline (each edge has a typed reason).
+
+### Graph 2 — Document Routing Graph
+
+Nodes are documentation targets and change categories; edges express "when this kind of code changes, those docs must be updated." The job of this graph is _propagation_ — preventing stale docs by making the doc-update obligation visible at the point of code change. The graph is most valuable when it is read by humans during PR review and by agents during the wrap / closeout protocol, not when it is read by no one.
+
+### Graph 3 — Memory Index
+
+Nodes are persistent memory topic files (decisions, observations, durable preferences); edges are the index entries that point from a topic table to the underlying file. The job of this graph is _cross-session knowledge persistence_ — the answer to "what did we already decide about X, why, and when did the decision become true." A memory graph that records facts but not the _why_ and _how_ of decisions cannot answer audit questions like "why did the agent choose Y?". Workspaces that need decision provenance extend the memory graph with the Process Knowledge Ontology pattern (modeling decisions, triggers, state transitions, and outcomes as first-class entities).
+
+### Graph 4 — Script / Command Registry
+
+Nodes are scripts and commands; edges are the categorisations that group them by purpose. The job of this graph is _agent tooling discovery_ — when an agent needs a deterministic script or a slash command, the registry is what makes it findable without trial-and-error.
+
+### Cross-graph edges
+
+The four graphs are _interconnected_. The cross-graph edges are where most of the propagation value lives:
+
+| From        | To      | Edge type                                          | Example                                                                   |
+| ----------- | ------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
+| Skill       | Script  | `key_file` (frontmatter `paths` or body reference) | A health-audit skill points at the script that runs the audit             |
+| Skill       | Skill   | `adjacent` / `boundary` / `verify_with`            | Frontmatter relations                                                     |
+| Script      | Command | `consumed_by`                                      | A loop-supervisor script is consumed by a manage-style command            |
+| Memory      | Skill   | `informs`                                          | A memory file recording a billing strategy informs an agent-routing skill |
+| Doc-routing | Doc     | `requires_update`                                  | A code change row points at the docs that must be updated together        |
+
+A workspace that names all four graphs _and_ their cross-graph edges has a complete map. A workspace that names only the skill graph has roughly a quarter of the picture.
+
+## 2. Edge Types in the Skill Graph
+
+The skill graph uses three relation types. Each has a different _meaning_ and a different _cap_. Mixing them collapses the graph into noise.
+
+| Type          | Recommended cap | Meaning                                                                                                              | Example                                                     |
+| ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `adjacent`    | ≤ 5 per skill   | Closely related — teach together; an agent loading one would benefit from also loading the other                     | A data-reconciliation skill ↔ a financial-correctness skill |
+| `boundary`    | ≤ 5 per skill   | Contrasting — "do NOT use X for this; use Y instead." The router should _exclude_ the boundary skill when both match | A financial-correctness skill ↮ a data-visualisation skill  |
+| `verify_with` | ≤ 3 per skill   | Cross-check skill output against this skill before trusting it                                                       | A financial-correctness skill → a code-logic skill          |
+
+The caps exist to prevent edge inflation. A skill with 12 `adjacent` relations is not "well-connected" — it is a hub that pulls every adjacent traversal toward itself, hiding more specific signals. Edge discipline beats edge volume.
+
+### `boundary` is exclusion, not adjacency
+
+The most common edge-type confusion: putting "topical neighbour" skills in `boundary`. Boundary edges tell the router "if both this skill and the boundary skill match, route AWAY from the boundary skill" — they are _exclusion-with-a-reason_, not "see also." Putting a skill in `boundary` that should be in `related` will hijack the boundary skill's positive cases and depress its routing-eval pass rate. When in doubt, prefer `related` and only promote to `boundary` when the two skills genuinely _compete_ for the same prompt with different correct answers.
+
+## 3. Orphan Detection
+
+An **orphan** is a node with zero (or near-zero) incoming edges. Nothing points at it, so traversal cannot reach it; agents have to know its exact name to find it. In a healthy graph, the orphan rate is below 10%. In an unhealthy graph it is the majority — and adding more skills makes the problem worse, not better, because each new skill is also unreachable.
+
+### Orphan-detection recipe
+
+1. Rebuild the graph from authored artefacts (deterministic synthesis).
+2. Walk every node, count its `degree` (incoming + outgoing).
+3. Flag every node with degree ≤ 1 as an orphan candidate.
+4. For each orphan: identify its domain cluster (layer, keywords, examples) and find 3–5 sibling skills that _should_ reference it.
+5. Add `relations` to the orphan and reciprocal references to its siblings — bidirectionally. A one-way edge from the orphan does not solve discovery, because the existing skills are where traversal _starts_.
+
+### Remediation priority
+
+Fix orphans in order of blast radius, not alphabetically:
+
+1. **Security and compliance skills** — data exposure risk if agents miss them
+2. **Correctness-critical skills** — financial, accounting, time, irreversible mutations
+3. **Integration skills** — webhook signature verification, idempotency, retry
+4. **Infrastructure skills** — operational impact (deploy, migrate, rollback)
+5. **UX / display skills** — lower blast radius; fix once higher-priority orphans are gone
+
+## 4. Graph Connectivity Metrics
+
+These are the vital signs of a skill graph. Run them after every batch of skill additions or edge edits.
+
+| Metric              | Formula                                | Healthy band    | Unhealthy signal                                                                 |
+| ------------------- | -------------------------------------- | --------------- | -------------------------------------------------------------------------------- |
+| **Connectivity**    | `connected_skills / total_skills`      | > 95%           | Multiple disconnected clusters indicate domain silos                             |
+| **Average degree**  | `total_edges × 2 / total_nodes`        | > 5             | Below 3 means the graph is too sparse for traversal to be useful                 |
+| **Orphan rate**     | `nodes with degree ≤ 1 / total_nodes`  | < 10%           | Above 30% means agents cannot discover most of the library                       |
+| **Max degree**      | Highest degree of any node             | < 30            | A single node with degree 50+ is a hub-and-spoke anti-pattern                    |
+| **Cluster count**   | Connected components                   | < 3 (ideally 1) | Many clusters means the workspace has informal silos that traversal can't bridge |
+| **Hub-spoke ratio** | `nodes with degree > 15 / total_nodes` | < 5%            | More than 10% means the graph is degenerating into a star around a few mega-hubs |
+
+### Five deterministic signals for graph synthesis
+
+Synthesise the skill graph from these signals only — never from an LLM at runtime:
+
+1. **Explicit prose references** — patterns like "Do NOT use X — use skill-name" in skill bodies
+2. **Manual `relations` frontmatter** — author-declared edges
+3. **Bundle co-membership** — skills declared in the same routing bundle
+4. **Shared routing labels / triggers** — overlapping `triggers` or label declarations
+5. **Keyword overlap** — shared keywords via the routing-config map
+
+A graph built from these signals is _reproducible_: rebuild today and tomorrow and the edges are identical. A graph that uses LLM inference at synthesis time will drift on every rebuild and the routing layer cannot trust it.
+
+## 5. Change-Propagation Analysis
+
+When a single artefact changes, trace the propagation across all four graphs. This is the discipline that prevents silent staleness.
+
+### Propagation checklist
+
+| Step | Action                                                                                                                                             | Tool                                      |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| 1    | Read the document-routing graph. Find the change category (e.g., "DB migration", "webhook handler change") and list the docs that must be updated. | Read the routing table                    |
+| 2    | Grep the changed file path / function name across all `*.md` for stale references                                                                  | `grep -r "<changed_id>" --include="*.md"` |
+| 3    | Check skill key-file sections for references to the changed file                                                                                   | `grep -r "<changed_id>" skills/`          |
+| 4    | Check the memory index for related topic files; update or add records if a decision changed                                                        | Read the memory index                     |
+| 5    | Verify no stale references remain — run any doc-verification gate the workspace ships                                                              | Local doc-verification script             |
+
+Each step exercises a different edge type. Skipping a step leaves a stale edge somewhere in the system, and the staleness compounds — the next change inherits a wrong baseline.
+
+## 6. Anti-Patterns
+
+| Anti-pattern                                                                      | Why it fails                                                                                  | What to do instead                                                                                      |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Edge inflation** — adding 10+ `adjacent` relations to one skill                 | Creates a hub-and-spoke; traversal pulls everything toward the hub and hides specific signals | Cap at 5; pick the most semantically-close siblings                                                     |
+| **One-way edges** — adding edges _from_ a new skill _to_ existing skills only     | Existing skills stay orphaned; nothing points at them in the new direction                    | Add reciprocal references — update the existing skill too                                               |
+| **Optional-metadata mindset** — treating relations as nice-to-have                | Orphan rate drifts up silently; eventually most skills are unreachable                        | Graph maintenance is a quality gate; CI should fail on degraded connectivity                            |
+| **AI-inferred runtime edges** — letting an LLM "infer" relations on every rebuild | Graph drifts non-deterministically; routing layer cannot trust it                             | Use deterministic signals at synthesis time; use AI only as an _authoring suggestion_ the human accepts |
+| **Ignoring cross-graph edges** — only maintaining the skill graph                 | Skills reference scripts and memory references skills, but those edges are unmaintained       | Map all four graphs and the cross-graph edges between them                                              |
+| **Boundary-as-adjacency** — putting topical neighbours in `boundary`              | Hijacks the neighbour's positive cases; depresses its routing-eval                            | Use `related` for neighbours; reserve `boundary` for genuine routing-exclusion                          |
+
+## Verification
+
+- [ ] All four graphs in the workspace are named and have an authoritative source-of-truth file
+- [ ] Cross-graph edges are explicit (skill → script, skill → memory, doc-routing → doc, script → command) — not implicit
+- [ ] Graph rebuild is deterministic — same input artefacts produce identical edge set on every run
+- [ ] Orphan rate is below 10%; orphans above the threshold have been triaged by blast radius
+- [ ] Average degree is above 5; max degree is below 30; cluster count is 1 (or small with explicit reason)
+- [ ] Edge-type discipline is enforced — `adjacent` ≤ 5, `boundary` ≤ 5, `verify_with` ≤ 3 per skill
+- [ ] `boundary` is used for routing-exclusion only, not for "see also"
+- [ ] The change-propagation checklist has been applied for the most recent significant change, end-to-end across all four graphs
+- [ ] CI (or an equivalent gate) fails the merge when connectivity, orphan rate, or max degree breaches the healthy bands
+
+## Do NOT Use When
+
+| Use instead            | When                                                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `skill-scaffold`       | Authoring or restructuring a single SKILL.md — the per-skill craft, not the whole-graph architecture                                |
+| `skill-infrastructure` | Running the live skill library tooling — census, overlap detection, routing-gap reporting, drift checks on individual skills        |
+| `graph-audit`          | Validating that one skill's frontmatter matches the schema and its relation targets exist                                           |
+| `skill-router`         | Deciding which skill activates for a specific query at dispatch time — that is the _consumer_ of this graph, not the graph's design |
+| `documentation`        | Writing the prose of a single document for a human reader — the change-propagation framework here is upstream                       |
+| `code-review`          | Reviewing AI-generated code — orthogonal concern                                                                                    |