agentleFS
Sign inStart free
mmaripanguecmmaripanguec/dev-sdd-kit/.claude/skills/system-map/SKILL.md

system-map

Skill2 starsChanged 4 months agoMITView on GitHub

Generates or updates the SYSTEM PACK (<prefijo>-sistema, the junctions and the mental model that live in no repo) and the mapa-sistemas index. Use when the system has ≥2 repos with packs, when asked for "the system map"/"how the repos connect", or when /spec-create detects the system pack is missing.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    ALL repos and their seals.

    line 25
  2. Very specific:

    Create the context skill <prefix>-architecture from templates/skill-architecture.md (fill {{PREFIX}}, {{SYSTEM}}, {{REPO_TRIGGERS}} = the …

    line 46
  3. Distinctive:

    NOT re-index or re-read code for what is already documented.

    line 50
  4. Distinctive:

    ASK. Never normalize silently.

    line 58

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “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

Generate .claude/skills/<prefijo>-sistema/SKILL.md (prefix = registry_pack_prefix from repo-lib) and update the index .claude/skills/mapa-sistemas/SKILL.md. The system pack carries what lives in no repo: the mental model and the junctions.

1. Inputs

  1. Full registry (repos.yaml) + current seals (stamp_of_repo).
  2. System as-is: knowledge/as-is/system.md (cross-repo graph) — regenerate if it is old.
  3. The existing per-repo packs (<prefijo>-*): the junctions are born from crossing their two ends. If the pack of a central repo is missing, generate that one first with /repo-map (or ask the human whether to prioritize).
  4. Verification of each junction AT BOTH ENDS of the code: an arrow asserted by only one side is a hypothesis, not a fact.

2. Write the system pack

  • Template: templates/pack-system.md; frontmatter generado_desde: with ALL repos and their seals; verificado: today.
  • The ⭐ mental model is THE claim that changes how the system is understood (with its cross-repo evidence chain). If there is not one yet, say so honestly: "I have not yet found the central claim".
  • "Pitfalls" and "What I DON'T know" never empty. Budget ~150 lines; detail goes to references/.

3. mapa-sistemas index

  • Template: templates/pack-index.md: table of systems with the REAL context state (which packs exist, which are current — use scripts/freshness.sh check and scripts/assertions.sh), where to start, and "What I DON'T know".

4. AS-IS architecture document (knowledge, arc42 + C4)

  • Author/refresh the curated narrative in knowledge/architecture/<system>.narrative.md (seed it from templates/knowledge-architecture.narrative.md on first run): mental model, seams, endpoints, decisions, risks — the analysis that lives in no repo. The derived data (topology, dependencies, metrics) is injected by the generator.
  • Generate both formats: ./scripts/generate-architecture.sh writes knowledge/architecture/<system>.{md,html}.
  • Create the context skill <prefix>-architecture from templates/skill-architecture.md (fill {{PREFIX}}, {{SYSTEM}}, {{REPO_TRIGGERS}} = the system's repo names/aliases, {{SEALS_FRONTMATTER}}, {{FECHA}}) so agents load the document as context on those triggers and do NOT re-index or re-read code for what is already documented.

5. Assertions, verification and closure

  • Each important junction → assertion in scripts/assertions.d/<sistema>.sh (ideally one per end). Run the suite: green is mandatory.
  • scripts/freshness.sh check green for the touched packs.
  • INCONSISTENCIES (the as-is graph contradicts a pack, a junction is not confirmed at the other end, an ADR is refuted): STOP AND ASK. Never normalize silently.
  • Commit: docs(packs): pack de sistema <prefijo>-sistema + indice.
  • Final summary: mental model + map of verified arrows + what is missing.

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.

Check your setup, free