Claude Skill

analyze-repo

Generate an evidence-backed visual architecture and technical-debt audit for an entire repository.

LLM Mart · 0 points · 2 views 86 listing impressions 0 install-command copies
Download kriscard-skills-skills_dev_analyze-repo-08395f4.zip · 17 KB

Install

skills CLI npx skills add https://github.com/kriscard/Skills/tree/main/skills/dev/analyze-repo
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kriscard-skills@llmmart
Git git clone https://github.com/kriscard/Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kriscard/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Repository Analysis

Produce a standalone HTML audit that makes the repository's architecture, dependency pressure, and highest-impact debt visible. Every claim must trace to measured output or named files; uncertainty stays explicit.

Workflow

1. Build the evidence ledger

Inspect repository guidance and the environment before choosing commands. Exclude generated, vendored, cache, and dependency directories from source metrics. Collect:

  • repository shape: source files, languages, top-level modules, entry points
  • organization: feature/layer/package ownership and whether the directory layout matches the runtime and domain model
  • composition: how modules collaborate, where interfaces and seams live, and whether complexity is concentrated or repeated across callers
  • architecture: runtime boundaries, data flow, persistence, external systems
  • dependencies: high fan-in modules, dependency direction, seam violations, and cycles when tooling can verify them
  • patterns: established frontend, backend, integration, state, persistence, and design patterns; competing implementations and incomplete migrations
  • hotspots: large or complex files, mixed responsibilities, TODO/FIXME clusters
  • decisions: existing ADRs and consequential choices whose rationale is absent from repository documentation
  • verification: test locations, test runner configuration, coverage artifacts, and CI checks

Use deterministic commands or project tooling for counts and graph claims. Record an evidence ledger with these fields:

Field Requirement
Claim One falsifiable statement
Evidence Command output, configuration, or exact file/module paths
Method How the evidence was collected
Confidence verified, supported, or unverified

Coverage is a measured value only when a coverage artifact or executed coverage command provides it. Otherwise report test signals and label coverage Not measured.

Load references/architecture-decisions.md when consequential architecture is present. Search existing ADRs and design docs before calling a decision undocumented. Record observed choices separately from inferred rationale; missing business constraints remain questions, not findings.

Delegate broad repository exploration through the available subagent mechanism when useful. Give the explorer the ledger schema and require specific paths for every non-empty category. The parent agent owns verification of returned claims.

Done when every candidate finding has evidence and a confidence label.

2. Synthesize findings

Load the codebase-design skill and use its terms consistently. Assess modules through their interfaces, implementations, seams, adapters, depth, leverage, and locality. Reserve boundary for a domain or deployment boundary; use seam for a place where behavior can vary.

Group verified evidence into architecture, organization, composition, dependencies, patterns, hotspots, decisions, and verification. Identify established frontend/backend patterns before treating variation as inconsistency. Merge duplicate symptoms that share one root cause. Rank findings by:

  1. production or security risk
  2. change amplification and defect risk
  3. developer friction and onboarding cost
  4. low-urgency cleanup

Each finding must name the affected scope, explain its impact, and recommend a bounded next action. Separate observed facts from interpretation. Apply the deletion test to suspected pass-through modules, and call a seam real only when multiple adapters or another demonstrated variation justify it.

For consequential undocumented choices, add an ADR candidate rather than inventing rationale. Link recorded decisions to their existing ADR. Hand an unresolved candidate to the architect skill to compare options and recommend a decision; draft the ADR only after that decision is resolved and the user asks for the durable artifact.

Done when the top findings are evidence-backed, use the shared vocabulary, distinguish established patterns from accidental variation, and are ordered by impact.

3. Choose the visualization

Every report needs an architecture visualization, but no renderer is mandatory. Choose the smallest format that communicates the evidence:

  • Inline SVG: preferred for a curated architecture, data-flow, or hotspot diagram. Load references/svg-patterns.md.
  • Zoomable diagram: use when labels or edges cannot remain legible at report width. Load references/diagram-shell.md; its shell accepts inline SVG, including SVG pre-rendered by a graph tool.
  • HTML/CSS structure: use for a simple layer stack or small relationship map that needs no freeform edges.

Generated report text must be HTML-escaped. SVG text and attributes must be XML-escaped. If a graph renderer is used, encode labels for that renderer before rendering and embed the resulting SVG rather than repository-controlled markup.

Done when the chosen visualization exposes real repository boundaries and every highlighted problem maps to a finding.

4. Generate the report

Read these references before writing:

  1. references/report-design-system.md
  2. references/report-components.md
  3. references/html-report-template.md
  4. references/architecture-decisions.md when ADRs or ADR candidates exist
  5. the visualization reference selected in Step 3

Assign the path once and reuse it:

REPORT_PATH="${TMPDIR:-/tmp}/repo-analysis-$(date +%Y%m%d-%H%M%S).html"

The report must contain:

  1. repository identity, analysis date, scope, and one-sentence assessment
  2. measured summary with provenance and explicit unknowns
  3. architecture visualization and explanatory caption
  4. module-design assessment using the shared vocabulary
  5. ranked findings with severity, confidence, evidence, impact, and next action
  6. decision record linking existing ADRs and listing qualified ADR candidates
  7. hotspot/file tour focused on the evidence, not an exhaustive file list
  8. prioritized recommendations and a verification checklist

Done when the file exists, contains no unresolved template variables, and every finding rendered in the report has a matching ledger entry.

5. Render-check and deliver

Open the report through available browser automation when possible; otherwise use the platform opener (open, xdg-open, or start). Inspect the rendered page at desktop and narrow widths. Verify:

  • no script, style, font, or network errors are required for core content
  • architecture labels, edges, legends, and captions remain legible
  • tables/cards do not overflow or hide evidence
  • keyboard focus is visible on interactive controls
  • light and dark color schemes preserve contrast
  • zoom controls, when present, keep the caption outside the clipped viewport and work at maximum zoom and every pan extreme

Fix failures and repeat the check. Deliver the report path and summarize the top 3–5 findings with their confidence. Offer a follow-up architectural grilling session; begin it only when the user opts in.

Completion Gate

The analysis is complete only when:

  • every reported claim has evidence and a confidence label
  • organization, composition, and established frontend/backend patterns were inspected using the shared codebase vocabulary
  • consequential choices link to an existing ADR, qualify as an ADR candidate, or state why no decision record is needed
  • coverage and complexity are measured or explicitly marked unmeasured
  • the report contains a renderer-appropriate architecture visualization
  • repository-controlled text is encoded for its output context
  • the rendered report passes desktop, narrow-width, and diagram checks
  • the top 3–5 findings are ranked by impact and surfaced to the user

References Routing Table

Priority Load when Reference
1 — Required Generating any report references/report-design-system.md
1 — Required Building report sections references/report-components.md
1 — Required Assembling the final HTML references/html-report-template.md
2 — Conditional Existing ADRs or consequential undocumented choices appear references/architecture-decisions.md
2 — Conditional Rendering a curated inline SVG references/svg-patterns.md
2 — Conditional The diagram needs zoom or pan references/diagram-shell.md
Files (skills)
  • references
    • architecture-decisions.md 3.6 KB
      Loading…
    • diagram-shell.md 3.9 KB
      Loading…
    • html-report-template.md 11.4 KB
      Loading…
    • report-components.md 5 KB
      Loading…
    • report-design-system.md 3.3 KB
      Loading…
    • svg-patterns.md 3.4 KB
      Loading…
  • SKILL.md 8.4 KB
    ---
    name: analyze-repo
    description: Generate an evidence-backed visual architecture and technical-debt audit for an entire repository.
    disable-model-invocation: true
    ---
    
    # Repository Analysis
    
    Produce a standalone HTML audit that makes the repository's architecture,
    dependency pressure, and highest-impact debt visible. Every claim must trace to
    measured output or named files; uncertainty stays explicit.
    
    ## Workflow
    
    ### 1. Build the evidence ledger
    
    Inspect repository guidance and the environment before choosing commands. Exclude
    generated, vendored, cache, and dependency directories from source metrics.
    Collect:
    
    - repository shape: source files, languages, top-level modules, entry points
    - organization: feature/layer/package ownership and whether the directory layout
      matches the runtime and domain model
    - composition: how modules collaborate, where interfaces and seams live, and
      whether complexity is concentrated or repeated across callers
    - architecture: runtime boundaries, data flow, persistence, external systems
    - dependencies: high fan-in modules, dependency direction, seam violations, and
      cycles when tooling can verify them
    - patterns: established frontend, backend, integration, state, persistence, and
      design patterns; competing implementations and incomplete migrations
    - hotspots: large or complex files, mixed responsibilities, TODO/FIXME clusters
    - decisions: existing ADRs and consequential choices whose rationale is absent
      from repository documentation
    - verification: test locations, test runner configuration, coverage artifacts,
      and CI checks
    
    Use deterministic commands or project tooling for counts and graph claims. Record
    an evidence ledger with these fields:
    
    | Field | Requirement |
    |---|---|
    | Claim | One falsifiable statement |
    | Evidence | Command output, configuration, or exact file/module paths |
    | Method | How the evidence was collected |
    | Confidence | `verified`, `supported`, or `unverified` |
    
    Coverage is a measured value only when a coverage artifact or executed coverage
    command provides it. Otherwise report test signals and label coverage `Not
    measured`.
    
    Load `references/architecture-decisions.md` when consequential architecture is
    present. Search existing ADRs and design docs before calling a decision
    undocumented. Record observed choices separately from inferred rationale; missing
    business constraints remain questions, not findings.
    
    Delegate broad repository exploration through the available subagent mechanism
    when useful. Give the explorer the ledger schema and require specific paths for
    every non-empty category. The parent agent owns verification of returned claims.
    
    Done when every candidate finding has evidence and a confidence label.
    
    ### 2. Synthesize findings
    
    Load the `codebase-design` skill and use its terms consistently. Assess modules
    through their interfaces, implementations, seams, adapters, depth, leverage, and
    locality. Reserve *boundary* for a domain or deployment boundary; use *seam* for
    a place where behavior can vary.
    
    Group verified evidence into `architecture`, `organization`, `composition`,
    `dependencies`, `patterns`, `hotspots`, `decisions`, and `verification`. Identify
    established frontend/backend patterns before treating variation as inconsistency.
    Merge duplicate symptoms that share one root cause. Rank findings by:
    
    1. production or security risk
    2. change amplification and defect risk
    3. developer friction and onboarding cost
    4. low-urgency cleanup
    
    Each finding must name the affected scope, explain its impact, and recommend a
    bounded next action. Separate observed facts from interpretation. Apply the
    deletion test to suspected pass-through modules, and call a seam real only when
    multiple adapters or another demonstrated variation justify it.
    
    For consequential undocumented choices, add an **ADR candidate** rather than
    inventing rationale. Link recorded decisions to their existing ADR. Hand an
    unresolved candidate to the `architect` skill to compare options and recommend a
    decision; draft the ADR only after that decision is resolved and the user asks
    for the durable artifact.
    
    Done when the top findings are evidence-backed, use the shared vocabulary,
    distinguish established patterns from accidental variation, and are ordered by
    impact.
    
    ### 3. Choose the visualization
    
    Every report needs an architecture visualization, but no renderer is mandatory.
    Choose the smallest format that communicates the evidence:
    
    - **Inline SVG:** preferred for a curated architecture, data-flow, or hotspot
      diagram. Load `references/svg-patterns.md`.
    - **Zoomable diagram:** use when labels or edges cannot remain legible at report
      width. Load `references/diagram-shell.md`; its shell accepts inline SVG,
      including SVG pre-rendered by a graph tool.
    - **HTML/CSS structure:** use for a simple layer stack or small relationship map
      that needs no freeform edges.
    
    Generated report text must be HTML-escaped. SVG text and attributes must be
    XML-escaped. If a graph renderer is used, encode labels for that renderer before
    rendering and embed the resulting SVG rather than repository-controlled markup.
    
    Done when the chosen visualization exposes real repository boundaries and every
    highlighted problem maps to a finding.
    
    ### 4. Generate the report
    
    Read these references before writing:
    
    1. `references/report-design-system.md`
    2. `references/report-components.md`
    3. `references/html-report-template.md`
    4. `references/architecture-decisions.md` when ADRs or ADR candidates exist
    5. the visualization reference selected in Step 3
    
    Assign the path once and reuse it:
    
    ```bash
    REPORT_PATH="${TMPDIR:-/tmp}/repo-analysis-$(date +%Y%m%d-%H%M%S).html"
    ```
    
    The report must contain:
    
    1. repository identity, analysis date, scope, and one-sentence assessment
    2. measured summary with provenance and explicit unknowns
    3. architecture visualization and explanatory caption
    4. module-design assessment using the shared vocabulary
    5. ranked findings with severity, confidence, evidence, impact, and next action
    6. decision record linking existing ADRs and listing qualified ADR candidates
    7. hotspot/file tour focused on the evidence, not an exhaustive file list
    8. prioritized recommendations and a verification checklist
    
    Done when the file exists, contains no unresolved template variables, and every
    finding rendered in the report has a matching ledger entry.
    
    ### 5. Render-check and deliver
    
    Open the report through available browser automation when possible; otherwise use
    the platform opener (`open`, `xdg-open`, or `start`). Inspect the rendered page at
    desktop and narrow widths. Verify:
    
    - no script, style, font, or network errors are required for core content
    - architecture labels, edges, legends, and captions remain legible
    - tables/cards do not overflow or hide evidence
    - keyboard focus is visible on interactive controls
    - light and dark color schemes preserve contrast
    - zoom controls, when present, keep the caption outside the clipped viewport and
      work at maximum zoom and every pan extreme
    
    Fix failures and repeat the check. Deliver the report path and summarize the top
    3–5 findings with their confidence. Offer a follow-up architectural grilling
    session; begin it only when the user opts in.
    
    ## Completion Gate
    
    The analysis is complete only when:
    
    - every reported claim has evidence and a confidence label
    - organization, composition, and established frontend/backend patterns were
      inspected using the shared codebase vocabulary
    - consequential choices link to an existing ADR, qualify as an ADR candidate, or
      state why no decision record is needed
    - coverage and complexity are measured or explicitly marked unmeasured
    - the report contains a renderer-appropriate architecture visualization
    - repository-controlled text is encoded for its output context
    - the rendered report passes desktop, narrow-width, and diagram checks
    - the top 3–5 findings are ranked by impact and surfaced to the user
    
    ## References Routing Table
    
    | Priority | Load when | Reference |
    |---|---|---|
    | 1 — Required | Generating any report | `references/report-design-system.md` |
    | 1 — Required | Building report sections | `references/report-components.md` |
    | 1 — Required | Assembling the final HTML | `references/html-report-template.md` |
    | 2 — Conditional | Existing ADRs or consequential undocumented choices appear | `references/architecture-decisions.md` |
    | 2 — Conditional | Rendering a curated inline SVG | `references/svg-patterns.md` |
    | 2 — Conditional | The diagram needs zoom or pan | `references/diagram-shell.md` |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.