Skill Graph Audit

# Interpreting Graph Metrics

## Isolate Taxonomy

A skill flagged as "isolate" (zero inbound, zero outbound) is not
necessarily broken. Per `docs/skill-integration-guide.md#skill-role-taxonomy`, three legitimate
roles produce zero edges:

### 1. Library skills

Skills consumed via `dependencies:` frontmatter from other skills
or via Python imports rather than `Skill()` calls. Example:
`abstract:shared-patterns`. **Action**: confirm `dependencies:` field
in callers.

### 2. Entrypoint skills

Skills invoked directly by users via slash commands or by an
external orchestrator (e.g. `egregore:summon`). Example:
`abstract:plugin-review`. **Action**: confirm a corresponding
command file exists in `plugins/<plugin>/commands/`.

### 3. Hook-target skills

Skills that hooks redirect to. Example: `imbue:proof-of-work`.
**Action**: confirm a `PreToolUse`/`PostToolUse` hook in
`plugins/<plugin>/hooks.json` references the skill.

A skill that fits none of the three is a true orphan and a
candidate for retirement.

## Hub Sensitivity

Skills with high inbound count are load-bearing. Before retiring
or splitting one:

- Run `rg "Skill\\(<plugin>:<name>\\)" plugins/` to enumerate callers
- Open a deprecation issue with at least 30-day notice
- Provide a migration target in the deprecation note

The current top-5 hubs (as of 2026-04-25) are:

1. `scribe:slop-detector`
2. `attune:project-brainstorming`
3. `sanctum:git-workspace-review`
4. `attune:project-planning`
5. `attune:project-specification`

## Dangling Reference Triage

| Class | Default action |
|-------|----------------|
| bugs | Fix in the same PR; do not merge with bugs > 0 |
| external | Confirm external plugin is documented in plugin.json |
| placeholders | Annotate with `<!-- template -->` to suppress |

## Cross-Plugin Coupling

A high count of cross-plugin edges (src plugin != dst plugin) is
healthy ecosystem behaviour, not a problem. A high count of
intra-plugin edges (src plugin == dst plugin) suggests a
plugin-internal federation worth documenting in the plugin's
README.

## Common False Positives

- Skill names in code blocks demonstrating example usage are still
  parsed. If documenting a hypothetical skill, use `<plugin>:<name>`
  without backticks or surround with `<!-- example -->`.
- Skill names mentioned in `docs/decisions/` outside SKILL.md files
  are not parsed (only SKILL.md is the source of truth).


---
name: skill-graph-audit-usage
description: CLI reference and example workflows for the skill graph audit tool.
---

# Usage Reference

## CLI Flags

```text
python3 plugins/abstract/scripts/skill_graph.py [OPTIONS]

  --plugins-root PATH    Root containing <plugin>/skills/<name>/ tree
                         (default: plugins)
  --top-n INT            Top N hubs/orchestrators to show (default: 10)
  --format {text,json}   Output format (default: text)
  --output PATH          Write to file instead of stdout
```

## Common Workflows

### Pre-release dangling-ref check

```bash
python3 plugins/abstract/scripts/skill_graph.py \
  --plugins-root plugins --format json --output /tmp/graph.json

python3 -c "
import json
report = json.load(open('/tmp/graph.json'))
bugs = report['dangling_refs']['bugs']
if bugs:
    print(f'BLOCKING: {len(bugs)} dangling refs')
    for b in bugs:
        print(f'  {b[\"source\"]} -> {b[\"target\"]}')
    raise SystemExit(1)
print('OK: 0 internal dangling references')
"
```

### Find consolidation candidates

Hubs with >5 inbound references are core API; orchestrators with
>5 outbound references are coordination points. The intersection
(hub AND orchestrator) is the federation backbone.

```bash
python3 plugins/abstract/scripts/skill_graph.py --top-n 20 \
  | tee /tmp/graph.txt
```

### Update composition documentation

Generate the federation table for `docs/quality-gates.md` from
report JS