skill-graph-analytics
Weekly fleet analytics over the per-project skill-graph projections: consolidate root + Projects/<co-x> graphs into a dated snapshot, triage skill convergence (consolidation/promotion candidates), delivery drift (root skills missing from projects), and root-graph orphans (4-way cross-check), and record findings. Use when: the weekly analytics cadence fires (manual until the Friday full-override revival — see When to Run), the user says "skill-graph analytics", "fleet skill graph", "skill graph report", or asks which skills the project fleet carries, which root skills never reached projects, whether any agent or skill is orphaned, or what changed fleet-wide since last week.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- skill-graph-analytics
- owner
- pm
- scope
- workspace
- status
- active
- version
- 1.4.0
- metadata
- { "type": "process", "triggers": [ "skill-graph analytics", "fleet skill graph", "skill graph report", "skill graph fleet report", "skill convergence triage", "orphan agent check", "orphan skill check" ] }
- relates_to
- [ { "type": "composes_with", "skill": "project-resync" }, { "type": "relates_to", "skill": "context-commonization-review" } ]
- description
- Weekly fleet analytics over the per-project skill-graph projections: consolidate root + Projects/<co-x> graphs into a dated snapshot, triage skill convergence (consolidation/promotion candidates), delivery drift (root skills missing from projects), and root-graph orphans (4-way cross-check), and record findings. Use when: the weekly analytics cadence fires (manual until the Friday full-override revival — see When to Run), the user says "skill-graph analytics", "fleet skill graph", "skill graph report", or asks which skills the project fleet carries, which root skills never reached projects, whether any agent or skill is orphaned, or what changed fleet-wide since last week.
- l2_propagate
- false
- last_reviewed
- 1794096000000
- prerequisites
- workspace-root CWD; docs/skill-graph.json + Projects/<co-x>/docs/skill-graph.json projections present
03 SKILL.md 正文
Skill: skill-graph-analytics
Weekly fleet analytics over the per-project skill-graph projections
(Projects/<co-x>/docs/skill-graph.json, root docs/skill-graph.json).
One run answers: which skills does the fleet carry, which root skills never
reached the projects, how far has each project drifted from the root
projection, and what is NEW or VANISHED fleet-wide since the last snapshot?
Triage only — never auto-modify. This skill produces tickets and findings; it does not edit skills, promote content, or rewrite graphs.
When to Run
- Weekly cadence — NO scheduled runner invokes this skill as of 2026-11-03 (automation roster: 01:30 fleet-review+resync, 04:00 governance-ticket — neither carries the weekly consolidation; the old 02:30 reference here rotted, T-20261101-004). Revival home DECIDED 2026-11-03 (T-20261101-004): the 01:30 fleet runner's FRIDAY FULL OVERRIDE carries the weekly consolidation (one prompt-line addition, no new schedule; runner prompt updated via automation tooling). Until that override next fires, run it manually at the start of a weekly maintenance session.
- On demand — after a fleet-wide skill promotion/upgrade wave, before a consolidation decision, or whenever skill-graph drift is suspected.
Step-by-Step Procedure
1. Run the fleet report
bun scripts/skill-graph-fleet-report.ts
Read-only over all inputs. Writes one machine snapshot per local calendar date:
memory/skill-graph-metrics/snapshot-<YYYY-MM-DD>.json (same-date reruns
overwrite). First run establishes the baseline — no NEW/VANISHED diff exists yet.
Projects without a graph projection are skipped with a note; zero graphs found
exits 1 (fix the generator, bun scripts/generate-skill-graph.ts, before triage).
Fleet membership SSOT (DEC-20261107-01): the report's project set comes from
lib/fleet.ts — Projects/co-* directories minus the exclusions recorded in
docs/fleet-membership.json (verify with bun scripts/fleet-list.ts --json).
Never derive the set with a raw Projects/co-* glob; convergence denominators
count members only.
2. Read the snapshot and the report
- Per-project stats + Jaccard distance vs root — bigger distance = narrower or more divergent projection; small projects are expected to diverge, a large project with rising distance is a delivery-gap signal.
- Presence matrix + top skills — fleet presence counts per skill
capability (frontmatter
capability, default = skill name; v1 project graphs derive it from the bare node id, so v1 and v2 graphs join on the same key). - Skill convergence by capability — capabilities carried by >= 3 project
graphs, split into
converged(one content hash),convergence-with- divergence(>= 2 hashes) andhash-unknown(a v1 project graph carries no hashes yet); see §3 and §3.4. - Root skills missing per project — the delivery-drift surface.
- Root-graph orphan candidates — graph-isolated root skills/agents with the 4-way cross-check axes (see §3.5); feeds the orphan triage rules.
- NEW/VANISHED vs the previous snapshot — fleet-wide skill evolution.
3. Triage (judgment — not automatable)
| Signal | Threshold | Action |
|---|---|---|
Capability present in project graphs but absent from the root graph, converged class (single content hash) |
>= 3 project graphs | Consolidation/promotion candidate — file a ticket: bun scripts/ticket.ts create --manual "skill-graph: <capability> converged in N projects, absent from root — consolidation review" --priority normal (routes through §3.7.5 governance-backlog triage) |
Capability in the convergence-with-divergence class (>= 3 projects, >= 2 content hashes) |
any | Reconciliation candidate, not a promotion candidate — see §3.4; never auto-promote |
Capability in the hash-unknown class |
>= 3 project graphs | Treat as a promotion candidate by presence only; content equality is unverified until the carrying v1 projects are upgraded (upgrade-project delivers the v2 generator) — compare the SKILL.md files by hand before filing a promotion ticket |
| Root skill missing from many projects | missing from >= 3 project graphs | Delivery-gap candidate — file a ticket naming the skill and the missing projects (likely template-delivery drift; check templates/common/skills/ and the variant contract) |
| NEW/VANISHED skills in the diff | any | Verify each is intentional (new skill landed / skill deprecated) — unexplained entries are tickets |
| Root-graph orphan candidate (report section "Root-graph orphan candidates") | any isolated skill/agent | Apply the 4-way orphan criteria below — never treat graph isolation alone as proof of orphanhood |
| Everything else | — | No action; the snapshot is the record |
3.4 Divergence triage (capability-based convergence)
Since skill-graph v2 (ADR-0060 Amendment 11) a skill node's identity is
skill:<scope>/<name> with a content_hash, and fleet convergence groups by
capability rather than by raw node id, so same-named skills whose content
differs no longer look identical. For each convergence-with-divergence
capability in the report:
- Read the hash groups (
hash: projects) and diff the SKILL.md copies of the largest and smallest group. - Classify: fork (intentional variant specialisation — set a distinct
capability:in the forked SKILL.md frontmatter, or keep and record why), drift (accidental divergence — reconcile to one copy, then the group becomesconvergedand a promotion candidate), or rename (same job, different name — set the samecapability:on both so they group). - File one reconciliation ticket per capability (
bun scripts/ticket.ts create --manual "skill-graph: <capability> diverged across N projects — reconcile" --priority normal); never edit the project copies from this skill.
The root docs/skill-graph.md section "Same-Name Divergence (E2)" and
bun scripts/verify-skill-graph.ts carry the same signal inside the workspace
(version-drift = same version, different content — bump or reconcile).
bun scripts/generate-skill-graph.ts --impact <skill> lists the agents,
procedures, scopes, tests and contracts a change to a skill touches.
3.5 Root-graph orphan cross-check (4-way criteria)
A root skill or agent is an orphan candidate only when it is graph-isolated (zero edges — reported in the fleet report's orphan section since fleet-report v1.1.0). Isolation alone is NOT proof: classify each candidate by crossing four axes, all reported in the same section:
| Axis | Meaning | How the report shows it |
|---|---|---|
| Definition | The node exists in the graph (skills/, agents/) | the isolation list itself |
| Registry | A SKILLS.md / roster row exists | registry ✓/✗ |
| Mirror | The 4 platform skill bases carry it | mirrors N/4 |
| Reference | Workflow docs mention it (bounded corpus: platform/agent context docs + procedures/ + process/) | refs N |
Triage rules:
- All four axes present (registry ✓, mirrors 4/4, refs > 0) → graph-edge
gap, not an orphan. Fix the graph, not the skill: add a hand-reasoned
docs/skill-graph.overrides.jsonentry (relates_to, withreason/since) or a workflow-doc citation, then regenerate. - Definition + Registry only (no mirror, no refs) → weak candidate — wire it into a workflow or schedule deprecation review.
- Missing registry row or mirrors → delivery drift — the standard registry/mirror fixes apply before any orphan verdict.
- Zero axes beyond definition → true orphan — retire via the skill/agent lifecycle manager.
- Agent candidates: mirror axis does not apply (agents are not mirrored); weigh roster presence (AGENTS.md §1/§4.1) and doc references instead.
Historical baseline (2026-09-23 audit): 12 L0 + 48 variant skills were graph-isolated; the workflow-doc citation scan (generator Source 4.8) plus four overrides entries brought L0 isolation to zero — variant-isolated skills remain on this cadence's triage list.
Centrality-readiness note (Phase 2, future work): presence counts are a
blunt proxy for importance. A later phase adds centrality ranking over the root
graph (degree/betweenness over step_uses_skill/used_by edges) per
docs/designs/2026-09-22-skill-graph-fleet-analytics-design.md — do not
over-prioritize a skill on presence alone today.
4. Record findings
Append a ## Skill-Graph Fleet Analytics section to the daily memory log
(memory/YYYY-MM-DD.md): snapshot path, headline stats (projects covered,
fleet skill count, top-3 by presence), every ticket filed, and any
delivery-gap or convergence observation that did not merit a ticket.
Notes
- Capability-keyed presence: presence is keyed by
capability(default = skill name). Semantic duplicates under different names need an explicit sharedcapability:in frontmatter (or content-similarity matching — out of scope, design doc §Out of Scope). Hashes cover SKILL.md only (supporting files underreferences/andscripts/are not hashed). - Snapshots accumulate under
memory/skill-graph-metrics/; they are the input for future trend analysis (Phase 3, future work). Do not hand-edit them.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.