agentleFS
MicrosoftKnown publishermicrosoft/cobol-docs-pipeline-sample/.github/skills/diagram-renderer/SKILL.md

diagram-renderer

Skill1 starsChanged 55 days agoMITView on GitHub

Author FILE-LEVEL Mermaid overviews for ONE mainframe or IBM i (AS400) source from `facts.json`. Emits call graph, COBOL control flow, IBM i CL command flow, JCL steps, CICS calls, SQL cursor lifecycle, and ER fragments when facts exist. USE FOR: IBM i CL/COBOL or mainframe diagrams. DO NOT USE FOR: per-section diagrams, SVG rendering, or index/complete authoring.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    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:

    Do not use this skill for:

    line 16
  2. Very specific:

    Use identifiers that match profile.yaml::identifier_lock_regex (default [A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?).

    line 40
  3. Very specific:

    Re-deriving collections: Always use facts.json collections as-is.

    line 101
  4. Very specific:

    Invented nodes: Every Mermaid node MUST trace back to an identifier present in the corresponding facts.json collection.

    line 102

≈ “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

Diagram Renderer (per-file, phase C)

LLM-driven phase-C authoring skill. Produces FILE-LEVEL overview .mmd Mermaid sources, one per non-empty collection in docs/_shared/<basename-with-ext>/facts.json. The skill packages the inputs deterministically and defines the kind-to-syntax mapping; the LLM call that fills the templates is invoked by the diagram-renderer agent.

When to Use

  • The user asks to "render the overview diagrams", "generate the call graph", "draw the JCL step flow", "author cics-calls.mmd", "produce the ER fragment for DEMO100".
  • Phase B has completed: docs/_shared/<file>/facts.json exists and its manifest_sha256 matches the current chunk-manifest.

Do not use this skill for:

  • Per-section .mmd files — those are produced by section-doc-writer at per-section scope.
  • .svg rendering — owned by phase D.
  • File-level prose (index.md / complete.md) — use section-doc-finalizer.

Output Contract

For file <basename-with-ext> and each non-empty source collection, emit:

Collection (in facts.json)Output fileMermaid kind
performsdocs/_shared/<file>/diagrams/call-graph.mmdflowchart LR
calls + incoming_xrefdocs/_shared/<file>/diagrams/inter-program-call-graph.mmdflowchart LR
go_tosdocs/_shared/<file>/diagrams/control-flow.mmdflowchart TD
jcl_stepsdocs/_shared/<file>/diagrams/jcl-steps.mmdflowchart TD
cl_commandsdocs/_shared/<file>/diagrams/cl-command-flow.mmdflowchart TD
exec_cicsdocs/_shared/<file>/diagrams/cics-calls.mmdsequenceDiagram
exec_sql (cursor stanzas)docs/_shared/<file>/diagrams/cursor-lifecycle.mmdstateDiagram-v2
data_recordsdocs/_shared/<file>/diagrams/er-fragment.mmderDiagram

Empty collections produce NO file. Stale .mmd files for collections that emptied between runs are deleted when --prune is passed.

Each .mmd MUST:

  • Begin with a Mermaid %% generated-from: <facts_sha8> %% comment so consumers can detect drift.
  • Use identifiers that match profile.yaml::identifier_lock_regex (default [A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?).
  • Reference only chunks/identifiers present in facts.json — no invented nodes.
  • Render inter-program-call-graph from the bundle's derived inter_program_calls collection. Each edge label is its call kind; inbound and outbound directions must be preserved. Exclude copybook edges.

Procedure

  1. Resolve inputs. Required artifact (under docs/_shared/<basename-with-ext>/):
    • facts.json (whole file — this is the per-file step, slicing does not apply). On any miss: exit 4 and tell the user to re-run phase B.
  2. Stale-input check. Re-compute sha256(facts.json bytes) and compare to the value embedded in any existing .mmd header. On mismatch, re-author (or delete with --prune).
  3. Assemble the prompt bundle. Invoke scripts/assemble-inputs.py — pure-deterministic packager. It loads facts.json, derives the non-empty collection set, and prints (or writes via --out) a single JSON object the LLM consumes:
    python .github/skills/diagram-renderer/scripts/assemble-inputs.py `
      --source repos/sample1/COBOL/DEMO100.CBL `
      --out  prompt-bundle.json
    Flags:
    • --source <path> (required).
    • --out <path> — write to file (default: stdout).
    • --profile <path> — override profile.yaml.
  4. Author. The diagram-renderer agent reads the bundle and writes one .mmd per non-empty collection.
  5. Validate mechanically. Invoke qa-reviewer --kind diagrams on the produced .mmd set.

Bundle Schema

{
  "bundle_version":   "1.0",
  "source_path":      "repos/sample1/COBOL/DEMO100.CBL",
  "source_kind":      "cobol|cl|jcl|proc|copybook|bms",
  "program_id":       "DEMO100",
  "facts_sha":        "<64-hex>",
  "manifest_sha":     "<64-hex>",
  "diagrams": [
    {
      "kind":        "call-graph",
      "mermaid":     "flowchart LR",
      "output_path": "docs/_shared/DEMO100.CBL/diagrams/call-graph.mmd",
      "facts_subset": { "performs": [ /* … */ ], "paragraphs": [ /* … */ ] }
    },
    /* one entry per non-empty collection, in stable order */
  ],
  "profile":          { /* loaded profile.yaml */ }
}

Determinism Rules

  • Bundle packager is fully deterministic: stable iteration order, sha256 over canonical-JSON of every facts_subset.
  • LLM authoring is non-deterministic but the shape is fixed: same kind → same Mermaid header, same identifier styling.
  • Pruning is opt-in via --prune to avoid silently deleting hand-edited .mmd files.

Resources

  • scripts/assemble-inputs.py — deterministic prompt-bundle packager.

Common Pitfalls

  • Authoring per-section .mmd here. Those belong to section-doc-writer per-section scope; mixing breaks the per-section/per-file boundary the DAG enforces.
  • Re-deriving collections. Always use facts.json collections as-is; do not re-parse the COBOL/JCL source.
  • Invented nodes. Every Mermaid node MUST trace back to an identifier present in the corresponding facts.json collection.

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.