agentleFS
Pearl1531Pearl1531/Archetype-talk/.claude/skills/graph-lint/SKILL.md

graph-lint

Skill2 starsChanged 49 days agoMITView on GitHub

Health check for the graph: dead links, incomplete Signals, orphans, stale data — proposes fixes, never rewires links without approval. Use on /graph-lint or after large edit batches/imports.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the mechanical linter, interpret its findings, and propose fixes.

    line 8
  2. Very specific:

    Run python3 scripts/graph_lint.py and show the output grouped as the script prints it (ERRORS / WARNINGS / INFO).

    line 21
  3. Very specific:

    If --fix (or the user asks): propose fixes per the approval rules below.

    line 23
  4. Distinctive:

    If the user declines a fix, leave it and don't re-propose it every run — note it as "known, accepted by researcher" in the summary.

    line 32
  5. Distinctive:

    Never edits files during the report phase.

    line 36
  6. Distinctive:

    Never deletes a Signal/Evidence file (even an orphan) — worst case it proposes archiving, user decides.

    line 37
  7. Very specific:

    Never touches Transcripts/ content.

    line 38

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

graph-lint — Graph health check

Run the mechanical linter, interpret its findings, and propose fixes. This skill reports and proposes — the researcher owns the graph.

Trigger

/graph-lint            ← full report
/graph-lint --fix      ← report, then walk through proposed fixes (with approval)

Also worth suggesting (not auto-running) after a big import (/dovetail-sync, /source-sync, /extract-findings --all).

Workflow

  1. Run python3 scripts/graph_lint.py and show the output grouped as the script prints it (ERRORS / WARNINGS / INFO).
  2. Interpret briefly — e.g. orphan Signals may simply belong to a persona not yet written (offer /persona-workshop), stale INFO items are candidates for a refresh round (/researcher for Evidence, real interviews for Signals).
  3. If --fix (or the user asks): propose fixes per the approval rules below.

Approval rules — the researcher stays in control

Hand-written links are the researcher's material. The AI never silently rewires the graph:

  • Trivial mechanical fixes — a link whose intended target is obvious but the path is broken (missing URL-encoding, a typo'd filename, a file that was renamed and every other reference already points to the new name): batch them into ONE list, show old → new for each, apply only after a single explicit yes.
  • Meaning-changing fixes — adding a link that didn't exist (e.g. wiring an orphan Signal to a Persona), removing a link, changing which entity something points to, or editing evidences: lists: propose each one individually with a one-line justification citing the content that supports it. These change what the graph claims, so they are individually approved, never batched.
  • Never "fix" a contradiction — conflicting Signals are data. If lint output or content review surfaces a semantic conflict, point to /contradictions instead of editing anything.
  • If the user declines a fix, leave it and don't re-propose it every run — note it as "known, accepted by researcher" in the summary.

What this skill never does

  • Never edits files during the report phase.
  • Never deletes a Signal/Evidence file (even an orphan) — worst case it proposes archiving, user decides.
  • Never touches Transcripts/ content.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.