Operational spec for agentskill. This file governs when to invoke, what to run, and in what order. For how to generate AGENTS.md, read SYSTEM.md — it is the behavioral bible. These two files are complementary. Neither is sufficient alone.

Purpose

Analyze one or more code repositories. Extract exact coding conventions. Synthesize a precise, forensic AGENTS.md that allows any agent to produce code indistinguishable from the existing codebase.

Generation Modes

agentskill supports two generation modes. The mode determines who authors the final document:

AI-led generation (skill mode — this file)

The model synthesizes the final AGENTS.md itself. CLI analyzer commands are used only for evidence gathering — to extract repository facts that the model cannot derive reliably from reading source files alone.

In skill mode, never call agentskill generate to produce the final AGENTS.md. The model is the author. Analyzer output is the raw material, not the finished product.

CLI static generation (operator mode)

The user runs agentskill generate directly. The packaged runtime emits markdown automatically. This is appropriate for deterministic direct generation without an LLM in the loop.

Use CLI generation only in non-LLM static/operator workflows where the user explicitly wants tool-generated markdown rather than AI-authored synthesis.

Rule: AI Authorship

The model authors the final document in skill mode.

Do not use agentskill generate or python scripts/generate.py to produce the final AGENTS.md when operating as a skill or in any AI-assisted workflow.
Use analyzer commands (analyze, scan, measure, config, git, graph, symbols, tests) to gather repository facts.
The final generated markdown must be synthesized by the AI from analyzer evidence, direct source file reads, and supporting documentation.
Treat analyzer outputs as evidence, not as the final authored document.

Trigger Phrases

Invoke this skill when the user says any of the following — or a close paraphrase:

"Generate an AGENTS.md"
"Extract my coding style"
"Analyze my repo for conventions"
"Create a style guide from my code"
"Update my AGENTS.md"
"My agent doesn't write code the way I do — fix it"

Do not invoke this skill for general code review, refactoring, or style advice not tied to generating AGENTS.md.

File Ecosystem

File	Role
`SKILL.md` (this file)	Operational spec: workflow, scripts, fallbacks, uncertainty handling
`SYSTEM.md`	Behavioral spec: what to generate, section by section, and how to evaluate it
`references/GOTCHAS.md`	Extraction errors to avoid; update this file whenever a new failure mode is discovered
`examples/`	Analyzer fixtures plus reference `AGENTS.md` examples; consult when handling an unfamiliar repo shape

Maintenance rule: If SYSTEM.md and SKILL.md ever contradict each other, SYSTEM.md wins. Fix SKILL.md to match.

Availability rule: If this skill was downloaded from ClawHub, or if examples/ is unavailable locally, do not consult examples/; skip it to avoid execution errors.

Workflow

Execute these steps in order. Do not skip steps. Do not reorder steps.

Step 1 — Collect

Ask the user for repo path(s). Accept one or more. Confirm before proceeding.

Provide the path(s) to your repository or repositories.
One path per repo. Multiple repos are supported.

If the user provides a monorepo, note this explicitly — steps 3 and 4 of SYSTEM.md apply.

Step 2 — Scan

Run the scan script to get the directory tree and source file inventory.

python scripts/scan.py <repo>

Outputs: annotated directory tree, source files grouped by language with line counts.

Use the output to decide what to read — largest files first, entry points and core modules before tests.

If the script fails: Manually walk the directory tree using available file tools. Note in your working context that the scan was manual — this affects reliability of the file inventory for large repos.

Step 3 — Measure

Run the measurement script to get exact formatting metrics.

python scripts/measure.py <repo>
python scripts/measure.py <repo> --lang python   # single language

Outputs: per-language indentation unit and size, line length percentiles (p95 and p99), blank line distributions between top-level definitions and between methods, trailing newline convention.

If the script fails: Proceed without exact measurements. Mark all formatting measurements in the generated AGENTS.md as [tentative] and note that manual inspection was used. Do not estimate percentiles — state the observable range instead.

Step 4 — Config

Run the config script to detect formatters, linters, and their exact settings.

python scripts/config.py <repo>

Outputs: per-language tool detection with relevant config excerpts — [tool.black], [tool.ruff], [tool.mypy], tsconfig.json, .prettierrc, .editorconfig, and equivalents.

If the script fails: Read config files directly from disk. Prioritize: pyproject.toml, package.json, .editorconfig, any .*rc files at the repo root. Do not guess what a formatter enforces — only document what you can read from config.

Step 5 — Read SYSTEM.md

Read SYSTEM.md fully before writing a single line of AGENTS.md.

Do not rely on memory of previous runs. Read it fresh every time.

Step 6 — Read Source Files

Read actual source files directly. Use the file inventory from Step 2 to choose what to read.

Minimum per language before drafting any section:

Priority	What to read
1st	Entry point and CLI files
2nd	Core logic modules (largest non-test files)
3rd	At least one test file
4th	Package manifest (`pyproject.toml`, `Cargo.toml`, `package.json`, etc.)
5th	At least one utility or helper module

Minimum count: 3–5 files per language. For monorepos, 3–5 files per service.

Do not begin drafting until this step is complete.

Step 7 — Check GOTCHAS.md

Read references/GOTCHAS.md before drafting.

This file contains extraction and synthesis errors discovered from previous agentskill runs — false patterns, formatter assumption traps, monorepo boundary mistakes, and section omissions.

Step 8 — Consult Examples

Read the relevant file in examples/ if you are handling an unfamiliar repo shape.

If this skill was downloaded from ClawHub, or if examples/ is unavailable locally, skip this step to avoid execution errors.

Scenario	File to consult
Standard single-language repo	`examples/SINGLE_LANGUAGE.md`
Monorepo with multiple services	`examples/MONOREPO.md`
Multi-language single repo	`examples/MULTI_LANGUAGE.md`

If no relevant example exists: Proceed without one. Do not consult an example from a different repo shape — it will introduce structural assumptions that don't apply.

Step 9 — Choose Output Shape

Before generating, determine the output profile and layout. Skip this step only if the user has already specified both preferences.

Profile controls content density:

Profile	Description
`concise`	Shorter, high-signal operational guidance only
`comprehensive`	Full detail with representative snippets and expanded rationale

Layout controls output packaging:

Layout	Description
`single`	One complete markdown file (default)
`split`	Concise primary file plus comprehensive companion reference doc
`multifile`	Root index file plus one markdown file per section in a `.agentskill/` dir

Asking the user:

If generation intent is clear but neither profile nor layout has been specified, ask the user briefly:

Which output shape do you want?
Profile: concise or comprehensive
Layout: single file, split, or multifile

Handling partial or delegated preference:

User response	Action
Both profile and layout specified	Use their choices; do not ask again
One specified, the other missing	Ask only for the missing choice
"default" or "whatever is best"	Use profile `concise` and layout `single`
Only layout chosen	Use profile `concise` unless layout is `multifile`, then use profile `comprehensive`

Important: Do not silently choose split or multifile when the user has not requested a multi-document layout. These layouts produce multiple files and change how the output is consumed — the user must opt in explicitly.

For update workflows: Only single layout is supported. If the user requests split or multifile layout for an update, explain that only single layout is currently supported for updates, then proceed with single.

After selection, confirm the chosen shape in one line before proceeding:

Generating: profile=concise, layout=single

Step 10 — Synthesize

Follow SYSTEM.md section by section, in the exact order specified.

You are the author. Do not delegate final generation to agentskill generate. Compose each section from the evidence gathered in Steps 2–8 and the source reads in Step 6.

Source of truth per data type:

Data type	Source
Line length, indentation, blank line counts	Script output from Step 3
Formatter and linter settings	Script output from Step 4
Naming conventions	Direct source file reads (Step 6)
Error handling patterns	Direct source file reads (Step 6)
Import ordering	Direct source file reads (Step 6)
Comment and docstring style	Direct source file reads (Step 6)
Test patterns	Direct source file reads (Step 6)
Directory structure	Script output from Step 2
Git conventions	`.git/` config + commit log inspection

For qualitative sections such as naming, imports, error handling, comments, and testing, enrich from static source evidence first: concrete rules plus real snippets. Use analyzer output to find candidate files, not as the section body.

Apply the Mimicry Test from SYSTEM.md to each section before moving to the next. Do not batch-test at the end.

Step 11 — Handle Uncertainty

When you are uncertain about a pattern mid-synthesis, apply this decision tree — do not silently guess:

Is the pattern supported by fewer than 3 examples?
  YES → Mark the rule [tentative] and continue.

Is there genuine inconsistency with no dominant pattern?
  YES → State the inconsistency explicitly. Do not invent a rule.

Is an entire section unmeasurable (e.g. script failed, files unreadable)?
  YES → Surface this to the user before writing that section.
        Ask: "I couldn't reliably extract [section].
        Do you want me to skip it, mark it tentative, or provide the data manually?"

Is the uncertainty minor and isolated to one sub-rule?
  YES → Mark [tentative], continue, note it in the draft summary.

Never silently guess. Never invent a rule. Never omit a section without telling the user.

Step 12 — Write

Write the output according to the layout chosen in Step 9.

Layout: single — Write one AGENTS.md file.

Layout: split — Write two files:

AGENTS.md — concise primary with a link to the companion
AGENTS.reference.md — comprehensive companion reference

Layout: multifile — Write a root index plus per-section files:

AGENTS.md — root index with section links
.agentskill/01_OVERVIEW.md, .agentskill/02_REPOSITORY_STRUCTURE.md, ... — one file per section, each with a backlink to the root

If this is a new file: Write directly.

If an existing AGENTS.md is present:

Read the existing file first.
Present a diff-style summary of what will change and why.
Ask for confirmation before overwriting.

After writing, output a brief summary:

AGENTS.md written.
Profile: concise | Layout: single

Sections completed:    15 / 15
Tentative rules:       [list them, or "none"]
Sections with gaps:    [list them, or "none"]
Recommended follow-up: [e.g. "Run measure.py — line length marked tentative"]

Why Seven Scripts?

The scripts handle exactly and only what an LLM cannot do reliably from reading source files.

Script	Why it cannot be skipped
`scan.py`	Large repos exceed the context window; without a file inventory the agent reads arbitrarily, missing dominant patterns in unread files
`measure.py`	95th-percentile line length requires counting every line across every file — estimation from reading samples is structurally inaccurate
`config.py`	Formatter config files are ground truth; inferring what a formatter enforces from its output is unreliable and will drift as config changes
`git.py`	Commit log and branch history require `git log` access; source files alone do not reveal prefix conventions or merge strategy
`graph.py`	Import graph cycle detection and monorepo boundary identification require traversing all files simultaneously, not reading them one by one
`symbols.py`	Codebase-specific affix detection requires counting patterns across every identifier in the repo — impractical to do by reading samples
`tests.py`	Test-to-source mapping and framework detection require walking the full file tree; sampling misses coverage gaps and naming inconsistencies

Everything else — error handling patterns, comment style, docstring format, architectural rules — comes from reading source files directly. Do not run scripts for things you can read.

Scripts Quick Reference

All scripts require Python stdlib only. No installation needed beyond pip install -e ..

Analyzer scripts (for evidence gathering in skill mode):

# Aggregate analyzer wrapper
python scripts/analyze.py <repo>

# Directory tree and file inventory
python scripts/scan.py <repo>

# Formatting metrics (indentation, line length, blank lines, newlines)
python scripts/measure.py <repo>
python scripts/measure.py <repo> --lang python

# Formatter and linter detection with config excerpts
python scripts/config.py <repo>

# Commit log, branch naming, and merge strategy
python scripts/git.py <repo>

# Internal import graph, cycle detection, monorepo boundaries
python scripts/graph.py <repo>

# Symbol name extraction and codebase-specific affix detection
python scripts/symbols.py <repo>

# Test-to-source mapping, framework detection, fixture extraction
python scripts/tests.py <repo>

# Run all seven analyzers in parallel and merge output
agentskill analyze <repo> --pretty

CLI generation (for operator/static use only, not for skill mode):

# Direct static generation — do not use in skill/AI workflows
agentskill generate <repo>
agentskill generate <repo> --profile comprehensive
agentskill generate <repo> --layout split --out AGENTS.md
agentskill generate <repo> --layout multifile --out AGENTS.md

# Update or create AGENTS.md in place (only layout=single supported)
agentskill update <repo> --profile comprehensive

Analyzer scripts output JSON to stdout. Pass --pretty for human-readable output. Pass --out <file> to write to disk.

Boundary rule: In skill mode, the generate and update commands are available for the user's direct CLI use only. The model must not call them to produce the final AGENTS.md.

Uncertainty Reference

Situation	Action
Fewer than 3 examples for a rule	Mark `[tentative]`
Genuine inconsistency, no dominant pattern	State the inconsistency; do not invent a rule
Script failed, measurement unavailable	Mark affected measurements `[tentative]`; note manual inspection was used
Entire section unmeasurable	Surface to user; ask before proceeding
Existing `AGENTS.md` present	Diff and confirm before overwriting
No matching example in `examples/`	Skip Step 8; do not use a mismatched example
User requests update with split/multifile	Explain only single layout is supported for updates; proceed with single

Principles

These are reminders, not the full spec. The full spec is in SYSTEM.md.

Extract, don't guess. Every rule must be grounded in observed code.
Snippets are the spec. Every non-trivial rule needs a real code snippet.
Static enrichment beats metric summaries. Qualitative sections should read like observed code behavior, not analyzer tallies.
3 examples minimum. Fewer → [tentative]. Inconsistency → state it.
Scope every rule. Repo-wide vs. per-language vs. per-service — always explicit.
No statistics in output. No counts, percentages, or confidence levels in AGENTS.md.
Mimicry test per section. Apply it before moving on, not at the end.
Uncertainty surfaces up. Never silently guess. Never silently omit.
AI authors the final document. In skill mode, do not call generate to produce the final output. Analyzer commands gather evidence; the model writes the document.

Update references/GOTCHAS.md after every run where a new failure mode is discovered. Update this file whenever the workflow changes. If this file and SYSTEM.md contradict — SYSTEM.md wins.

name	agentskill
description	Let any agent produce code indistinguishable from the existing codebase.

SKILL.md — agentskill