Analyze New Repo

Produce a reliable repository analysis without pretending certainty where the evidence is thin.

The goal is not to generate a lightweight summary. The goal is to produce a compact, evidence-backed analysis that helps the reader understand:

what this project is really trying to do
how it is organized and how it runs
which design decisions define the repository
what constraints, risks, and blind spots matter most
where the architectural center of gravity really is

When To Use

Use this skill when the user:

brings in a new repository and wants orientation
asks what the project does or how it is structured
wants build, run, or test commands for an unfamiliar codebase
asks for a repo walkthrough or onboarding summary
wants a high-confidence first-pass architecture analysis before making changes

Do not use this skill for a narrow one-file question or a known bug in an already-understood codebase.

Working Style

Move from surface evidence to high-leverage internals.

Start with repository instructions and top-level docs before reading implementation files.
Prefer concrete evidence over guesswork.
Mark inference as inference.
Compress unimportant details.
Explain not just what exists, but why it matters.
Write like a senior engineer or code analyst: technically opinionated, calm, and precise.
Avoid sounding like an onboarding checklist or a generic repo summary.

Investigation Workflow

1. Establish Repository Context

Read the highest-value orientation sources first:

```
AGENTS.md
```
```
README*
```

top-level docs such as

docs/

CONTRIBUTING*

ARCHITECTURE*

CHANGELOG*

recent git history if it exists

Capture:

stated purpose
runtime and platform assumptions
documented build, run, and test commands
any local rules that affect future changes
what kind of repository this is: application, library, internal tool, template, skill pack, research repo, infrastructure repo, etc.

2. Inspect Repository Conventions and Workflow Signals

Look for contribution and workflow artifacts that reveal how the project is maintained:

```
.github/ISSUE_TEMPLATE/
```
```
.github/PULL_REQUEST_TEMPLATE*
```
```
CONTRIBUTING*
```
```
CODEOWNERS
```
```
CODE_OF_CONDUCT*
```

Capture only what changes how the repo should be read:

issue and PR expectations
testing or release expectations
ownership clues
screenshots, migration notes, or eval evidence required in changes

If these files do not exist, say so briefly and move on.

3. Map the Surface

Inspect the top-level structure before diving into source.

Identify:

main application directories
tests, scripts, docs, assets, config, and CI folders
dependency manifests
likely entrypoints
directories that appear central versus peripheral

If the repository is large, sample representative directories and say that you are sampling.

4. Identify Execution Flow

Use docs first, then verify against config files.

Find:

how the project starts
how it is built
how it is tested
deployment or release hints
environment assumptions and external services

If commands disagree across files, call that out explicitly.

5. Read the Critical Path

Open the central entrypoint and the main modules on the execution path.

For each important module, summarize:

role
key inputs and outputs
main collaborators
why it matters architecturally

Favor a small number of high-value modules over broad shallow coverage.

6. Assess Quality Signals

Look for:

test organization and obvious coverage shape
CI or automation
release flow
dependency hygiene
documentation completeness
maintenance hotspots or tight coupling

Report only what you can actually see.

7. Call Out Risks and Unknowns

Be explicit about:

missing documentation
unclear runtime assumptions
fragile setup steps
test blind spots
surprising dependencies
parts that need deeper validation before changes

Scale Strategy

Adjust depth to repository size instead of pretending every repo deserves the same treatment.

Small repos: read the main files directly and go deeper on the true control path.
Medium repos: inspect the full surface, then choose the 3-5 modules that define execution and architecture.
Large repos or monorepos: explicitly say you are sampling. Start from manifests, workspace config, root docs, CI, and top-level app/package directories before diving into internals.
If the repo is too large for full coverage, prefer breadth-first orientation plus one or two representative deep reads.

Monorepo Strategy

If the repository is a monorepo, do not describe it as if it were one application.

First identify the repository shape:

deployable applications
shared packages or libraries
infrastructure or devops directories
docs, examples, or auxiliary tooling

Then follow these rules:

Start with root-level manifests, workspace configuration, root README/docs, and CI workflows.
Use workspace manifests and CI to cross-check what is actually built, tested, and deployed.
Separate the repository into boundaries before summarizing behavior.
Identify which subprojects are primary and which are supporting.
After mapping the full shape, choose only the 1-2 most important subprojects for deeper analysis unless the user explicitly asks for exhaustive coverage.
Treat deployable apps, shared packages, and infrastructure as different architectural roles, not as peers in a flat list.
Call out when tests, CI, or deployment operate at different layers than the main application code.

When unsure, prefer a report structure like:

```
Repository Thesis
```
```
Repository Shape
```
```
Execution Model
```
```
Architectural Center of Gravity
```
```
Quality Signals and Risks
```

Use

references/monorepo-checklist.md

when the repo clearly has multiple packages, apps, or ownership boundaries.

Stack-Aware Hints

Let dependency manifests influence where you look first.

```
package.json
```
, workspace files,
```
turbo.json
```
,
```
pnpm-workspace.yaml
```
: check scripts, workspaces, app/package split, and likely frontend/backend entrypoints.
```
pyproject.toml
```
,
```
requirements*.txt
```
,
```
uv.lock
```
: check CLI entrypoints, package metadata, tool config, and Python runtime assumptions.
```
Cargo.toml
```
: identify binaries vs libraries, workspace members, and feature flags.
```
go.mod
```
: check module boundaries,
```
cmd/
```
directories, and internal package layout.
```
docker-compose*
```
,
```
Dockerfile*
```
, Terraform, Helm, or deployment config: use these as evidence for operational shape, not just packaging.

If the stack is not covered above, use manifest filenames, workspace config, source layout, and CI workflows to infer the same things: entrypoints, package boundaries, build paths, and deployment shape.

These are hints, not a rigid language-specific playbook. Use them to improve reading order and entrypoint detection.

Output Format

Use the report template in

references/report-template.md

as the structure guide. Use

references/checklist.md

when you need a compact execution checklist before writing. Use

references/monorepo-checklist.md

when the repository is a clear monorepo.

Your output must:

open with a short section called
```
Repository Thesis
```
include 4-6 sections total, chosen to fit the repository
use concrete headings instead of a fixed universal set when the repo warrants it
always cover: purpose, execution path, key architecture, and risks or quality signals
prefer flat bullets, but use short paragraphs when a section needs stronger synthesis
make each bullet do at least two jobs: state a fact and explain its implication

Good section names include:

```
Repository Thesis
```
```
Repository Shape
```
```
Execution Model
```
```
Architectural Center of Gravity
```
```
Project Conventions
```
```
Quality Signals and Risks
```
```
Distinctive Design Decisions
```
```
Unknowns Worth Verifying
```

Avoid mechanically reusing the same section titles for every repository if the result feels generic.

Evidence Rules

Cite concrete file paths for important claims.
Distinguish clearly between confirmed facts, informed inference, and unknowns.
Prefer statements tied to a specific file over unsupported summaries.
Do not invent architecture details that were not verified.
If you cannot verify something, say so directly.
Prefer observations that connect evidence to architectural or maintenance consequences.

Writing Quality Bar

The result should read like a short analyst report, not a lightweight orientation blurb.

Specifically:

Do not merely restate README prose.
Do not flatten every repository into the same summary shape.
Surface the design decisions that make this repository distinctive.
Highlight what a technically strong reader would actually need to know before changing the code.
Keep it readable, but do not optimize for brevity so hard that the analysis loses weight.
Prefer bullets that combine fact + interpretation + implication.
Keep sentences compact, but allow a little density when the repo deserves it.
Avoid a mechanically symmetrical report if the repository has one dominant idea.

analyze-new-repo

NPX Install

Tags

SKILL.md Content