agentleFS
hugobatistahugobatista/agent-skills/skills/review/architecture-brief/SKILL.md

architecture-brief

Skill1 starsChanged 57 days agoMITView on GitHub

Generate an architecture overview document from a pull request or local git diff. Detects the forge type (GitHub, Forgejo, GitLab) from the current repo and uses the appropriate CLI. Supports PR mode (pr brief #N, architecture-brief PR #N) and local diff mode (git brief, architecture-brief, architecture-brief --staged). Produces a concise brief with Mermaid diagrams explaining what was built and how it works. Triggered by: architecture-brief, pr brief, git brief.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    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. Distinctive:

    Do not generate a brief for:

    line 20
  2. Distinctive:

    If unsure, generate the brief — it's cheap and useful.

    line 27
  3. Distinctive:

    If both a PR number and a local diff context exist, PR mode wins.

    line 43
  4. Distinctive:

    If the forge CLI is not installed, fall back to the PR's web API or local-diff mode.

    line 51
  5. Distinctive:

    Read the diff to understand scope and identify key new files

    line 66
  6. Distinctive:

    Read the diff to understand scope

    line 75
  7. Distinctive:

    No worktree needed — files are in the current working tree

    line 76
  8. Distinctive:

    Read the diff and identify:

    line 80
  9. Very specific:

    If --output <path> was provided, use it directly

    line 94
  10. Very specific:

    When generating Mermaid diagrams, also load the mermaid-syntax skill for syntax rules that prevent parser errors.

    line 170
  11. Distinctive:

    If a worktree was created (PR mode):

    line 182

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

Architecture Brief (architecture-brief)

This skill generates an architecture overview document from a PR or local git diff — explaining what was built and how it works. It detects the forge from the current repo and adapts accordingly.

When to skip

Do not generate a brief for:

  • Bug fixes (PR closes an issue with a patch)
  • Small changes (< 100 lines)
  • Pure refactors with no behavioral change
  • Documentation-only PRs
  • Dependency bumps

If unsure, generate the brief — it's cheap and useful.

Workflow

1. Determine mode

Parse the user's input:

InputModeDescription
pr brief #<N>, architecture-brief PR #<N>PRAnalyze a specific PR
architecture-briefLocal (unstaged)Analyze current unstaged diff
architecture-brief --staged, git brief --cachedLocal (staged)Analyze staged changes only
architecture-brief --output <path>anyOverride output path
git brief --since <ref>Local (range)Analyze diff from <ref> to HEAD

If both a PR number and a local diff context exist, PR mode wins.

2. Detect forge (PR mode only)

Load the forge-detect skill. It detects the repository's forge and sets $FORGE_CLI, $FORGE_TYPE, and $FORGE_HOST. Use the command templates from forge-detect for PR info, diff, and files.

If the forge CLI is not installed, fall back to the PR's web API or local-diff mode. If the forge CLI is installed but not authenticated, fall back to local-diff mode and note it to the user.

3. Gather input

PR mode

  1. Fetch PR info (title, description, changed files count) using $FORGE_CLI
  2. Save the diff using the PR diff command from forge-detect
  3. Create a worktree:
    git fetch origin "pull/<N>/head:arch-brief-pr-<N>"
    git worktree add ../arch-brief-pr-<N> arch-brief-pr-<N>
  4. Read the diff to understand scope and identify key new files

Local mode

  1. Get branch name: git branch --show-current
  2. Get the diff:
    • Unstaged: git diff > /tmp/arch-brief.diff
    • Staged: git diff --cached > /tmp/arch-brief.diff
    • Range: git diff <ref>..HEAD > /tmp/arch-brief.diff
  3. Read the diff to understand scope
  4. No worktree needed — files are in the current working tree

4. Analyze architecture

Read the diff and identify:

  1. New modules/directories — new packages, subdirectories, or files that form a cohesive unit
  2. New data models — database tables, schemas, Pydantic models
  3. New API endpoints or CLI commands — routes, entry points, background workers
  4. New infrastructure patterns — outbox, CQRS, event sourcing, background jobs, caching
  5. New configuration — environment variables, feature flags, settings

For each, read the relevant source files from the worktree (PR mode) or working tree (local mode) to understand how they work.

5. Generate the brief

Build the output path:

  • If --output <path> was provided, use it directly
  • Otherwise:
    • PR mode: docs/pr-<N>-arch.md
    • Local mode: docs/<branch-name>-arch.md

Save to the resolved path with this structure:

# <Title> Architecture

<Context line: PR #<N> | branch <name>, <date>, +/- line stats>

## Overview

<2-3 paragraphs. What problem does this solve? What are the key design
decisions?>

## Key concepts

<Explain the core domain concepts introduced. Use subheadings.>

### <Concept 1>

<How it works, why it exists, what problem it solves.>

### <Concept 2>

...

## Data flow

<Use Mermaid diagrams. Choose the type that best fits:

- **flowchart** for component relationships and routing
- **sequenceDiagram** for request/response flows
- **stateDiagram-v2** for state machines

```mermaid
flowchart LR
    A[Component] --> B[Component]

Include a caption explaining what the diagram shows.

Configuration

<New settings introduced. Use a table.>
SettingDefaultPurpose
ENV_VARvalueDescription

Include only new configuration — not pre-existing settings.

API / CLI surface

<New public entry points. Use a table.>
TypePath / NameAuthPurpose
endpointGET /api/v1/footokenList foos
workerAPP_ROLE=worker—Background processor

Include only what this PR adds.

Limitations

<Known trade-offs, edge cases not handled, planned follow-ups.>

  • <Item 1>
  • <Item 2>

### Mermaid diagrams

When generating Mermaid diagrams, also load the `mermaid-syntax` skill for syntax rules that prevent parser errors.

### 6. Present to user

Display the generated brief content, then ask:

> What would you like to do with this architecture brief?
> 1. **Save as doc** — writes to `<resolved path>`
> 2. **None** — discard

### 7. Cleanup

If a worktree was created (PR mode):

```bash
git worktree remove ../arch-brief-pr-<N>
git branch -D arch-brief-pr-<N>
rm -f /tmp/arch-brief-<N>.diff

Skip cleanup if the user asks to keep the worktree for further work.

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.