# branch-inspector

Adopt this skill: https://proskills.md/skills/other/montimage-skills-skills-branch-inspector

Page: https://proskills.md/skills/other/montimage-skills-skills-branch-inspector
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/branch-inspector/SKILL.md
size: 8244
upstream: https://github.com/montimage/skills/blob/main/skills/branch-inspector/SKILL.md

````text
---
name: branch-inspector
description: "Inspect a git branch against main, summarize its commits, diff, merge status, and staleness, then emit a cleanup action plan. Use when reviewing or cleaning up one branch. Don't use for repo audits, multi-branch sweeps, or PR code review."
license: Apache-2.0
effort: high
metadata:
  version: 1.1.5
  author: Montimage
---

# Branch Inspector

Inspects a single git branch against `main` to support a cleanup decision. The skill produces a deep overview of what the branch contains, surfaces signals that inform the keep/delete/archive/PR decision, asks the user to choose, then emits a concrete action plan for the chosen path.

## When to use

- The user is cleaning up branches and wants to understand one before acting on it.
- The user names a specific branch ("look at `feature/foo`", "is `experiment/x` worth keeping?").
- The user wants a deep summary of what a branch implements before deciding its fate.

Do **not** use this skill for: scanning many branches at once, full repo audits, or reviewing a PR diff line-by-line.

## Inputs

The branch name is passed as an argument. If the user invokes the skill without one, ask which branch to inspect — do not default to the current branch silently.

The branch may be local (`feature/foo`), remote (`origin/feature/foo`), or both. Detect which exist and report both states.

## Prerequisites

Verify before running. Stop and tell the user if any check fails.

- Current directory is a git repository (`git rev-parse --git-dir` succeeds).
- `main` branch exists locally or on `origin` (`git rev-parse --verify main` or `origin/main`). If the project's primary branch is `master` or something else, ask the user to confirm the comparison base.
- The target branch exists locally or on `origin`. If neither, stop and tell the user.
- `gh` CLI is optional; used to detect linked PRs. If not available, skip the PR-check step rather than failing.

## Repo Sync Before Inspect (mandatory)

Inspection is read-only on the working tree but needs fresh refs to be accurate. Before inspecting:

```bash
git fetch origin --prune
```

`--prune` removes stale remote-tracking refs so the skill doesn't report a branch as "exists on remote" when it was deleted upstream. Do not check out the branch and do not modify the working tree during inspection.

## Workflow

### 1. Resolve the branch

Given the branch name, determine:

- Does it exist locally? (`git rev-parse --verify <branch>`)
- Does it exist on remote? (`git rev-parse --verify origin/<branch>`)
- Are local and remote in sync, or has one diverged from the other?

Pick the inspection target: prefer the local ref if both exist and are in sync, otherwise inspect each side separately and call out the divergence.

### 2. Build the overview

Collect signals across five groups: **identity & activity, merge status, diff scope, implementation depth, staleness**. Run independent git commands in parallel where possible. See `references/overview-fields.md` for the exact field list, the git commands per field, and how to use `git cherry` for squash-merge detection. The implementation-depth group is the one that matters most for the decision — go beyond stats and read the diff to explain what the branch does. If the diff is too large to read in full, spawn an Explore subagent rather than skimming superficially.

### 3. Present the overview

Output a structured report. Use this template:

```
◆ Branch Overview: <branch>
··································································
  Refs:               local=<yes/no> remote=<yes/no> in-sync=<yes/no>
  Tip:                <sha-short> <date> by <author>
  Diverged at:        <sha-short> <date>
  Activity:           <N> commits ahead, <M> commits behind main
                      last commit <X> days ago
  Authors:            <list>
  Diff:               <files> files, +<added>/-<removed> lines
  Top areas:          <dir1>, <dir2>, <dir3>
  Merge status:       <merged | squash-merged | unmerged>
                      cherry-equivalent: <K>/<N> commits already on main
  Linked PR:          <url or "none">
  Conflict risk:      <low | medium | high — files overlap recent main activity>
  Staleness:          <fresh | stale (>30d) | abandoned (>90d)>
  Intent:             <feature | refactor | bugfix | experiment | WIP | unclear>

What this branch implements:
<2-6 sentences describing the actual change, drawn from the diff>

Notable findings:
- <signal 1, e.g., "Adds X module under src/foo, no tests">
- <signal 2, e.g., "Last 3 commits are 'WIP', no rebase since main moved 47 commits">
- <signal 3>

Recommendation: <delete | archive | open PR | keep>
Reasoning: <one sentence>
```

The recommendation is a suggestion, not a decision. Always defer to the user.

### 4. Ask the user to decide

Present four options explicitly:

1. **Delete** — branch is obsolete, already merged, or abandoned with nothing worth saving.
2. **Archive** — preserve the work but get it out of the active branch list.
3. **Open a PR** — branch is ready or close to ready for review.
4. **Keep** — branch is still in active development; no action now.

Ask the user which path to take. Do not act until they answer.

If the user picks **Archive**, follow up with: "Tag-and-delete (`archive/<branch>` tag, then delete branch) or rename to `archive/<branch>`?" Do not assume.

### 5. Emit the action plan

Once the user has decided, output a numbered action plan with the exact commands. Do **not** execute them automatically — this is a cleanup workflow and the user should run the commands themselves or explicitly approve.

See `references/action-plans.md` for the four plan templates (delete, archive tag-and-delete, archive rename, open PR, keep). Pick the template matching the user's decision, substitute `<branch>`, and present the numbered steps to the user. For the PR template, fill in the title and body from the implementation summary built in step 2.

### 6. Stop

The skill emits the plan and stops. Executing destructive commands (`branch -D`, `push --delete`) is the user's call, not the skill's. If the user explicitly asks the skill to run the plan, confirm once before each destructive step.

## Step Completion Reports

Emit a report after the overview phase and after the plan phase.

```
◆ Branch Overview (step 1 of 2 — <branch>)
··································································
  Refs resolved:      √ pass
  Merge status:       √ pass
  Diff analyzed:      √ pass
  Implementation:     √ pass (deep read)
  PR check:           √ pass (or — gh CLI not available)
  ____________________________
  Result:             PASS
```

```
◆ Action Plan (step 2 of 2 — decision: <delete|archive|pr|keep>)
··································································
  Decision captured:  √ pass
  Plan emitted:       √ pass
  Commands listed:    √ pass
  ____________________________
  Result:             PASS
```

## Expected output

A complete run produces three artifacts in the chat, in order:

1. **Branch Overview block** matching the template in step 3 (refs, tip, activity, diff, merge status, linked PR, conflict risk, staleness, intent, "What this branch implements" prose, notable findings, recommendation).
2. **Decision prompt** listing all four options (delete / archive / open PR / keep). For archive, a follow-up prompt asking tag-and-delete vs rename.
3. **Action plan** — the numbered template from `references/action-plans.md` matching the user's choice, with `<branch>` substituted and (for PR) suggested title/body filled in.

See `references/example-output.md` for a worked example showing the overview block, decision prompt, and follow-up plan for an archived branch.

## Acceptance criteria

A run is correct when **all** of these hold:

- The skill ran `git fetch origin --prune` before reading any refs.
- The branch was resolved on both local and remote; divergence (if any) was reported.
- The Overview block contains every field li
````

## File: README.md
upstream: https://github.com/montimage/skills/blob/main/README.md

````text
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/logo/logo-white.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/logo/logo-black.svg">
    <img src="assets/logo/logo-black.svg" alt="Montimage Skills" width="320">
  </picture>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="#catalog"><img src="https://img.shields.io/badge/Skills-9-green.svg" alt="Skills"></a>
  <a href="https://github.com/Montimage/skills/stargazers"><img src="https://img.shields.io/github/stars/Montimage/skills?style=flat&color=yellow" alt="GitHub Stars"></a>
</p>

# Procedural skills your AI agent loads on demand

Nine `SKILL.md` packages for Claude Code, Codex, and any agent that reads
skill metadata. Each one encodes a structured workflow — what to check, in
what order, with what guardrails — so you stop re-explaining your process
every session.

```bash
npx skills add https://github.com/Montimage/skills
```

## Why use skills instead of prompts

You keep typing the same instructions: "review this PR but also check SQL
safety", "set up CI but use pnpm not npm", "make the branch cleanup
non-destructive". Prompts evaporate. The next session you write them again,
slightly differently, and your agent improvises.

A skill is the prompt frozen as code. Same trigger, same workflow, same
checks, every time.

## How it works

```mermaid
flowchart LR
    A[You: 'audit supply chain'] --> B{Agent reads<br/>SKILL.md metadata}
    B -->|description matches| C[Load skill body]
    C --> D[Run structured workflow]
    D --> E[Approval gates<br/>before mutating files]
    E --> F[Output + diff]
```

The agent matches your request against each skill's `description` field. The
chosen skill's body loads on demand, runs its workflow, and stops at human
approval gates before changing anything.

## Catalog

Find the skill by what you'd type. Every row is a working trigger phrase.

### Shipping and releases

| You say | Skill | Outcome |
|---|---|---|
| "review this branch" / "branch cleanup" | [branch-inspector](skills/branch-inspector/) | Per-branch diff/merge/staleness report, then you pick delete/archive/PR/keep |
| "set up CI" / "add pre-commit hooks" | [devops-pipeline](skills/devops-pipeline/) | Detects stack, generates pre-commit + GitHub Actions, no YAML from scratch |
| "create an installer" / "install on any OS" | [install-script-generator](skills/install-script-generator/) | One `curl \| sh` script with OS/arch detection, verify, rollback |

### Quality and security

| You say | Skill | Outcome |
|---|---|---|
| "audit supply chain" / "harden dependencies" | [supply-chain-audit](skills/supply-chain-audit/) | Detect→audit→plan→apply for npm/pip/Docker/Actions; approval gated |
| "add more tests" / "find untested code" | [test-coverage](skills/test-coverage/) | Lists untested branches and error paths, then writes the missing tests |
| "is this skill safe?" / "audit this skill" | [skill-auditor](skills/skill-auditor/) | Scans a third-party skill for prompt injection, creds, shell risks |

### Documentation and open source

| You say | Skill | Outcome |
|---|---|---|
| "the README is a mess" / "organize docs" | [docs-generator](skills/docs-generator/) | Restructures scattered docs into a hierarchy with Mermaid diagrams |
| "make this open source" / "OSS readiness" | [oss-ready](skills/oss-ready/) | Adds README/CONTRIBUTING/LICENSE/CoC/SECURITY + 8-section audit |
| "full OSS prep" / "open-source this repo" | [oss-ready-flow](skills/oss-ready-flow/) | End-to-end 6-step orchestrator (audit, cleanup, docs, README, publish) |

## Install

Install the whole pack:

```bash
npx skills add https://github.com/Montimage/skills
```

Or pick one:

```bash
npx skills add https://github.com/Montimage/skills --skill supply-chain-audit
```

Verify in Claude Code:

```bash
claude --list-skills | grep -E 'branch-inspector|supply-chain'
```

## Use it

The trigger phrases above are the API. Type them naturally:

```text
> Audit supply chain on this repo
> Inspect the branch feature/legacy-payment
> Make this project OSS-ready
```

The agent picks the matching skill from `description` metadata and runs it.

## Anatomy of a skill

```
supply-chain-audit/
├── SKILL.md          # YAML metadata + workflow instructions
├── references/       # Loaded on demand (per-ecosystem rules, templates)
├── scripts/          # Runnable helpers
├── evals/            # Test prompts + assertions
└── docs/             # Human-only (README, eval report)
```

Loading is progressive:

```mermaid
flowchart TD
    A[Metadata: name + description<br/>~100 tokens, always loaded] --> B
    B[SKILL.md body<br/>loaded when skill triggers] --> C
    C[references/, scripts/<br/>loaded by skill on demand]
```

Token cost stays low because only the matching skill's body enters context.

## FAQ

**Which agents work?** Claude Code, Codex, and any tool that reads `SKILL.md`
frontmatter. No agent-specific bindings.

**Free for commercial use?** Yes. Apache 2.0.

**How do I write my own?** Fork a skill and edit `SKILL.md`. The frontmatter
schema is documented in [CONTRIBUTING.md](CONTRIBUTING.md).

**What if a skill modifies my repo wrong?** Every mutating skill (oss-ready,
devops-pipeline, supply-chain-audit, etc.) gates writes behind explicit user
approval and prints a diff before applying.

**Security?** Run `skill-auditor` on any third-party skill before installing.
For vulnerabilities here, see [SECURITY.md](SECURITY.md).

<details>
<summary><b>Project layout</b></summary>

```
skills/
├── skills/                       # 9 skills, one per directory
├── assets/                       # Logo and screenshot assets
├── docs/                         # Project documentation
│   ├── ARCHITECTURE.md
│   ├── CHANGELOG.md
│   └── DEVELOPMENT.md
├── LICENSE                       # Apache 2.0
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── SECURITY.md
```

</details>

<details>
<summary><b>Skill anatomy and progressive disclosure</b></summary>

Each skill ships a `SKILL.md` with YAML frontmatter (`name`, `description`,
`version`) and a markdown body. The agent reads metadata first; on match it
loads the body; the body points to `references/` and `scripts/` as needed.

Three levels:

1. **Metadata** — `name` + `description`, always in context, ~100 tokens.
2. **Body** — `SKILL.md` markdown, loaded on activation, target ≤500 lines.
3. **Resources** — files under `references/` and `scripts/`, loaded by the
   skill body when it needs them.

This keeps the context window small even with dozens of installed skills.

</details>

<details>
<summary><b>Contributing</b></summary>

1. Fork.
2. `git checkout -b feat/your-skill-name`
3. Create `skills/your-skill-name/SKILL.md` with valid frontmatter.
4. Add `evals/evals.json` with 2–3 realistic prompts.
5. Conventional commits: `feat(your-skill): ...`
6. Open a PR.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

</details>

<details>
<summary><b>License</b></summary>

Apache 2.0. Copyright [Montimage](https://www.montimage.com/).

</details>
````
