skill-dependency-graph

name	Skill Dependency Graph
description	Generate a navigable Mermaid dependency map of all skills with change detection, per-category drill-downs, and enabled overlay
var
tags	["meta","dev"]

${var} — Output path override. If empty, writes to docs/skill-graph.md.

Today is ${today}. Generate a navigable, decision-ready Mermaid map of all Aeon skills. Skip notify and PR when nothing changed.

Steps

1. Fingerprint inputs and check for change

Build an input fingerprint:

{
  sha1sum aeon.yml skills.json
  for f in skills/*/SKILL.md; do
    awk '/^---$/{n++;next} n==1{print FILENAME": "$0}' "$f"   # frontmatter only
    grep -hE '^depends_on:|^- skill:|consume:|parallel:|trigger:' "$f" || true
    grep -hoE 'memory/(topics|state)/[a-zA-Z0-9_.-]+' "$f" | sort -u
  done | sha1sum
} > /tmp/skill-graph.fingerprint

Compare against memory/topics/skill-graph-state.json (key input_fingerprint). If identical:

• Append ## skill-graph block to memory/logs/${today}.md: SKILL_GRAPH_NO_CHANGE — N skills, identical fingerprint
• Exit silently. No notify. No PR. No file rewrite.

If state file is missing → mode = SKILL_GRAPH_NEW. Otherwise → mode = SKILL_GRAPH_OK.

2. Parse all inputs (explicit + derived)

Explicit edges:

• aeon.yml → per-skill enabled, schedule, var, model; chains: blocks (steps:, consume:, parallel:); reactive: blocks (trigger:, on:, when:)
• Each skills/*/SKILL.md → frontmatter name, tags, depends_on: array

Derived edges (this is the leverage):

• For each skill, grep memory/topics/*.md and memory/state/*.json references. Classify as write if surrounding 3 lines match (write|save|append|>|update)\b.*(topics|state)/, else read. A write→topic from skill A and a read→same topic from skill B yields a shared-state edge A -..-> B.
• Skills tagged research writing to articles/*.md (or having articles/ in their output description) → automatic content-pipeline edges to syndicate-article, rss-feed, update-gallery.
• Every skill writes memory/cron-state.json — collapse this into a single legend note rather than 90 edges to heartbeat/skill-health/skill-repair.

3. Categorize via skills.json

Use skills.json as the canonical category map (research, dev, crypto, social, productivity). For skills not in skills.json, fall back to the first matching tag.

4. Lint before write

Before writing any Mermaid, validate:

• Every [label] declaration has matching brackets
• Every edge A --> B references nodes declared in some subgraph
• Every click X "..." directive references a declared node and a path that exists on disk
• Every subgraph block opens with subgraph and closes with end

If any lint check fails → mode = SKILL_GRAPH_ERROR, abort write, notify with the failing rule, exit.

5. Generate the multi-diagram document

Write to docs/skill-graph.md (or ${var}). Structure:

1. Header — title, Auto-generated by skill-graph on ${today}, current mode
2. Verdict line — one of: ARCHITECTURE_OK (no structural change) / NEW_SKILLS: a, b / RETIRED_SKILLS: c / NEW_DEPS: A→B, ... / NEW_ENABLED: x
3. What changed since last run — diff against prior docs/skill-graph.md: added/removed nodes, added/removed edges, enabled-state flips. Skip section on SKILL_GRAPH_NEW.
4. Overview diagram — flowchart LR with 5 category subgraph boxes (no inner nodes) + cross-category edges + edge counts as labels
5. Self-healing loop callout — small dedicated flowchart LR showing heartbeat → skill-health → skill-evals → skill-repair → self-improve with the shared cron-state.json as a labeled state node
6. Per-category mini-diagrams — one flowchart LR per category. Inside: all nodes for that category, intra-category edges as solid/dashed/dotted, cross-category dependencies shown as faded :::external ghost nodes pointing into a side cluster
7. Click-through directives — every node in every diagram gets click slug "../skills/slug/SKILL.md" (Mermaid renders as hyperlinks on github.com). The first argument is the Mermaid node ID, so use the hyphenated skill slug as the ID throughout (e.g. skill-health[skill-health], not skill_health[skill-health]). Underscore IDs in one diagram with hyphenated targets in another silently break the click-binding.
8. Enabled overlay — Mermaid classes: class slug enabled (bold border, schedule annotation in label) for skills with enabled: true; class slug disabled (faded grey) for the rest. Class definitions:

   classDef enabled fill:#fff,stroke:#000,stroke-width:2px,color:#000
   classDef disabled fill:#f5f5f5,stroke:#bbb,color:#888
   classDef external fill:none,stroke:#bbb,stroke-dasharray:3 3,color:#888
   

9. Legend — edge types (--> depends_on, -.-> consume, -..-> reactive/shared-state); enabled vs disabled visual; click-to-source note
10. Summary table — total skills, by category, by status (enabled/disabled), edges by type
11. Source-status footer — skills parsed: N · depends_on: X · consume: Y · reactive: Z · shared-state derived: W · enabled: E/N · mode: SKILL_GRAPH_{OK,NEW,NO_CHANGE,ERROR}

6. Update README idempotently

if ! grep -q 'docs/skill-graph.md' README.md; then
  # insert under "Skills" header if present, else append
  ...
fi

Never re-insert. Never reformat existing lines.

7. Persist state

Write memory/topics/skill-graph-state.json:

{
  "generated_at": "${today}",
  "input_fingerprint": "<sha1>",
  "skills_total": 96,
  "enabled_count": 1,
  "edges": { "depends_on": 4, "consume": 4, "reactive": 1, "shared_state": 12 },
  "node_list_sha": "<sha1 of sorted slugs>",
  "edge_list_sha": "<sha1 of sorted edge tuples>"
}

Used next run for change detection (step 1).

8. Branch, commit, PR

git checkout -b skill-graph/${today} 2>/dev/null || git checkout skill-graph/${today}
git add docs/skill-graph.md memory/topics/skill-graph-state.json README.md
git commit -m "docs(skill-graph): regenerate map (${verdict_one_line})"
git push -u origin skill-graph/${today}
gh pr create --title "docs(skill-graph): ${verdict_one_line}" --body "..."

PR body includes: verdict line, what-changed diff, summary table, source-status footer.

9. Notify (gated)

• SKILL_GRAPH_NO_CHANGE → no notify (already exited at step 1)
• SKILL_GRAPH_NEW → notify: *Skill Graph initialized* — ${N} skills mapped across 5 categories. PR: ${url}
• SKILL_GRAPH_OK → notify only if verdict is not ARCHITECTURE_OK: *Skill Graph updated* — ${verdict_one_line}. PR: ${url}
• SKILL_GRAPH_ERROR → notify: *Skill Graph FAILED* — lint: ${rule}. No PR opened.

10. Log

Append to memory/logs/${today}.md:

### skill-graph
- Mode: SKILL_GRAPH_{OK|NEW|NO_CHANGE|ERROR}
- Verdict: ${verdict_one_line}
- Skills: ${N} (enabled: ${E})
- Edges: depends_on=${X}, consume=${Y}, reactive=${Z}, shared_state=${W}
- PR: ${url or "—"}
- Source-status: ${footer}

Sandbox note

No external APIs needed — all inputs come from local files. Standard git + gh CLI for branch/PR creation (already authenticated via GITHUB_TOKEN).

Constraints

• State file: memory/topics/skill-graph-state.json — auto-created on first run; safe to delete to force a full regeneration (next run will fall through to SKILL_GRAPH_NEW).
• Never silently regress an already-good output. If lint fails, abort with SKILL_GRAPH_ERROR rather than commit a broken diagram.
• SKILL_GRAPH_NO_CHANGE is the most common path on a stable architecture and must be silent — no PR, no notify, just a log line. Operator trains to trust the silence.
• Click-through paths must be relative from the output file's directory (e.g. ../skills/X/SKILL.md from docs/skill-graph.md) so they resolve on github.com.
• Enabled state comes from aeon.yml only — never infer from cron-state or recent runs (a skill can be enabled but not yet run).
• Do not expand every skill writes cron-state.json into N edges — collapse into one legend note. The graph is a map, not an audit log.