name

claude-atlas

description

Meta-skill for evolving the claude-atlas project itself. Use this skill whenever working inside the claude-atlas repository — adding new artifact kinds (agent/skill/command/memory + future ones), adding new edge detectors (duplicate, override, collision, reference + future ones), tuning heuristic thresholds (Jaccard, trigger overlap), extending the HTML report, or touching the Anthropic SDK LLM-judge pass. Triggers on: "claude-atlas", "atlas graph", "artifact detector", "edge kind", "jaccard threshold", "semantic duplicate", "trigger collision", "report template", "cytoscape", or any work inside this repo's `src/claude_atlas/` tree.

claude-atlas meta-skill

You are working on claude-atlas, a CLI that scans a user's Claude Code setup and renders a relationship graph. This skill tells you the invariants that must survive every change.

When to use

Adding new ArtifactKind values (e.g., hooks, plugins).
Adding new EdgeKind values or new detectors in analysis/graph.py.
Tuning thresholds (JACCARD_SUSPICIOUS, JACCARD_DUPLICATE, TRIGGER_COLLISION_MIN_SHARED).
Evolving the HTML report (report/renderer.py + report/templates/report.mustache).
Touching the LLM-as-judge pass in analysis/llm_judge.py.

Core invariants

Heuristics are deterministic and LLM-free by default. The --semantic flag is opt-in. Never make network I/O a default. The CLI must be usable offline.
Detectors are pure functions. detect_* in graph.py take list[Artifact] and return list[Edge]. No side effects, no I/O, no global state. Makes them trivially testable.
Artifact IDs are stable and unique. The current recipe is "{kind}:{scope}:{name}:{path}". If you change it, update every detector that builds edges by ID.
The HTML report is self-contained. Cytoscape is loaded via CDN, but there's no other runtime network dependency. Don't add fetches to the template.
PT-BR + EN docs are mandatory. Every user-facing doc change goes in both README.md and README.pt-BR.md. Keep them structurally identical.
Copyright / ownership: every new file Gabriel's tooling creates stays MIT. Never add a non-OSI-approved header.

Adding a new edge detector (pattern)

Add the enum value to EdgeKind in models.py.
If it should appear in the "Issues" tab, add it to _ISSUE_KINDS in report/renderer.py and to ScanResult.issues in models.py.
Write a detect_<thing>(artifacts: list[Artifact]) -> list[Edge] in analysis/graph.py. Keep it pure.
Call it from build_all_edges.
Pick a color in _edge_color (report/renderer.py) and add a legend entry in the Mustache template.
Write at least one focused test in tests/test_core.py that constructs artifacts by hand and asserts exactly the edges you expect.

Adding a new artifact kind

Add to ArtifactKind enum.
Extend scan_claude_dir in scanner/parsers.py to find it.
Add a color in _node_color and a legend dot in the template.
Decide whether existing detectors should include it. Default: most detectors skip MEMORY — follow that precedent unless there's a reason not to.

Threshold changes

Thresholds live at the top of analysis/graph.py as module constants. Never hardcode them inside detector bodies — keep them discoverable. If you add a new threshold, mention it in both READMEs' "What it detects" section.

LLM judge etiquette

llm_judge.py imports anthropic lazily inside refine_with_llm. Never add a top-level import.
The default model is pinned to DEFAULT_MODEL (currently claude-sonnet-4-6). The CLI already exposes --model for overrides — don't bypass it.
The judge only ever re-examines DUPLICATE_SEMANTIC edges. Don't widen its scope without updating docs.
Output must stay structured JSON. If you extend the verdict schema, update both the prompt and the parser together.

Testing discipline

pytest must pass on every commit. The suite is cheap; run it.
ruff check . and mypy are soft-gated (not strict), but new code should not introduce new warnings.
Prefer constructing Artifact objects directly in tests (see _make_artifact in test_core.py) rather than writing files to disk — fewer moving parts.

claude-atlas meta-skill

You are working on claude-atlas, a CLI that scans a user's Claude Code setup and renders a relationship graph. This skill tells you the invariants that must survive every change.

When to use

Adding new ArtifactKind values (e.g., hooks, plugins).

Adding new EdgeKind values or new detectors in analysis/graph.py.

Tuning thresholds (JACCARD_SUSPICIOUS, JACCARD_DUPLICATE, TRIGGER_COLLISION_MIN_SHARED).

Evolving the HTML report (report/renderer.py + report/templates/report.mustache).

Touching the LLM-as-judge pass in analysis/llm_judge.py.

Core invariants

Heuristics are deterministic and LLM-free by default. The --semantic flag is opt-in. Never make network I/O a default. The CLI must be usable offline.

Detectors are pure functions. detect_* in graph.py take list[Artifact] and return list[Edge]. No side effects, no I/O, no global state. Makes them trivially testable.

Artifact IDs are stable and unique. The current recipe is "{kind}:{scope}:{name}:{path}". If you change it, update every detector that builds edges by ID.

The HTML report is self-contained. Cytoscape is loaded via CDN, but there's no other runtime network dependency. Don't add fetches to the template.

PT-BR + EN docs are mandatory. Every user-facing doc change goes in both README.md and README.pt-BR.md. Keep them structurally identical.

Copyright / ownership: every new file Gabriel's tooling creates stays MIT. Never add a non-OSI-approved header.

Adding a new edge detector (pattern)

Add the enum value to EdgeKind in models.py.

If it should appear in the "Issues" tab, add it to _ISSUE_KINDS in report/renderer.py and to ScanResult.issues in models.py.

Write a detect_<thing>(artifacts: list[Artifact]) -> list[Edge] in analysis/graph.py. Keep it pure.

Call it from build_all_edges.

Pick a color in _edge_color (report/renderer.py) and add a legend entry in the Mustache template.

Write at least one focused test in tests/test_core.py that constructs artifacts by hand and asserts exactly the edges you expect.

Adding a new artifact kind

Add to ArtifactKind enum.

Extend scan_claude_dir in scanner/parsers.py to find it.

Add a color in _node_color and a legend dot in the template.

Decide whether existing detectors should include it. Default: most detectors skip MEMORY — follow that precedent unless there's a reason not to.

Threshold changes

LLM judge etiquette

llm_judge.py imports anthropic lazily inside refine_with_llm. Never add a top-level import.

The default model is pinned to DEFAULT_MODEL (currently claude-sonnet-4-6). The CLI already exposes --model for overrides — don't bypass it.

The judge only ever re-examines DUPLICATE_SEMANTIC edges. Don't widen its scope without updating docs.

Output must stay structured JSON. If you extend the verdict schema, update both the prompt and the parser together.

Testing discipline

pytest must pass on every commit. The suite is cheap; run it.

ruff check . and mypy are soft-gated (not strict), but new code should not introduce new warnings.

Prefer constructing Artifact objects directly in tests (see _make_artifact in test_core.py) rather than writing files to disk — fewer moving parts.