agentskill

Analyze a code repository and synthesize an AGENTS.md that lets any agent produce code indistinguishable from the existing codebase.

---

What It Does

agentskill is not a linter and not a style guide generator. It is a forensic extraction tool. It walks a repository, measures every line, reads every config file, and inspects the commit log — then synthesizes a precise behavioral spec for a code-generating agent.

The output is not advice. It is mimicry instructions.

---

How It Works

Seven analysis scripts run in parallel. Each extracts one class of signal that an LLM cannot derive reliably from reading source files alone:

Script	What it measures
scan.py	Directory tree, file inventory, suggested read order
measure.py	Exact indentation, line length percentiles, blank line distributions
config.py	Formatter, linter, and type-checker detection with config excerpts
git.py	Commit prefixes, branch naming, merge strategy, signing
graph.py	Internal import graph, circular dependencies, most-depended modules
symbols.py	Symbol name extraction, naming pattern clustering, affix detection
tests.py	Test-to-source mapping, framework detection, fixture extraction

Script output feeds directly into AGENTS.md synthesis. The synthesis step follows the behavioral spec in SYSTEM.md.

---

Install

pip install -e .

For local development:

python -m pip install -e '.[dev]'

To enable the commit-time checks after installing the dev environment:

pre-commit install

---

Development Checks

Run the canonical local checks:

ruff format .
ruff check .
mypy
pytest

To verify formatting without rewriting files:

ruff format --check .
ruff check .
mypy
pytest

mypy is the repo's configured type-check command. Its configuration in pyproject.toml covers agentskill/, scripts/, and tests/.

Optional commit-time hooks are available if you want them locally:

pre-commit install
pre-commit run --all-files

The pre-commit setup mirrors the lightweight formatting, lint, and type-check passes. Full pytest runs remain part of normal local verification and CI.

---

Usage

# Canonical installed CLI
agentskill analyze <repo> --pretty
agentskill scan <repo> --pretty
agentskill measure <repo> --lang python --pretty
agentskill config <repo> --pretty
agentskill git <repo> --pretty
agentskill graph <repo> --pretty
agentskill symbols <repo> --pretty
agentskill tests <repo> --pretty

# Write output to file
agentskill analyze <repo> --out report.json
agentskill analyze <repo> --reference ../reference-repo --pretty

# Generate AGENTS.md markdown directly
agentskill generate <repo>
agentskill generate <repo> --out AGENTS.md
agentskill generate <repo> --reference ../ref-a --reference ../ref-b
agentskill generate <repo> --interactive

# Update or create AGENTS.md in place
agentskill update <repo>
agentskill update <repo> --section testing
agentskill update <repo> --exclude-section git
agentskill update <repo> --force
agentskill update <repo> --out updated-AGENTS.md

# Retained wrapper entrypoints for operator/skill workflows
python scripts/scan.py <repo> --pretty
python scripts/measure.py <repo> --lang python --pretty

The installed agentskill command is the steady-state CLI surface, including local development after an editable install. The retained scripts/*.py wrappers exist for direct analyzer execution and skill/operator workflows; they are not the primary runtime surface.

Update Workflow

agentskill update <repo> analyzes the repository, regenerates AGENTS sections, merges them with any existing AGENTS.md, and writes the result back to <repo>/AGENTS.md by default. Use --section to limit regeneration to one or more named sections, --exclude-section to keep specific generated sections untouched, and --force for a clean-slate rebuild that drops old custom sections instead of preserving them.

Generate Workflow

agentskill generate <repo> analyzes the repository and prints a fresh generated AGENTS.md document to stdout. Use --out to write that markdown to an explicit file path. Unlike update, generate does not merge with an existing AGENTS.md and does not write back to <repo>/AGENTS.md unless you explicitly choose an output path.

Both analyze and generate also accept repeatable --reference flags. Local reference repositories must contain a readable AGENTS.md; when provided, generate embeds reference metadata in the rendered markdown and analyze validates the references without changing its JSON output shape.

generate --interactive is opt-in guided gap filling. It asks a small number of targeted questions only when important signals are missing or ambiguous, then injects those answers into the generated markdown as explicit interactive notes. When references already provide those conventions, the prompt count drops accordingly.

Repo-Local Feedback

Incremental updates can read an optional repo-local sidecar file named .agentskill-feedback.json. This file is explicit, version-controllable, and affects only the current repository. It is not hidden memory and it is not global learning.

{
  "sections": {
    "overview": {
      "prepend_notes": [
        "Mention that deployments go through GitHub Actions."
      ]
    },
    "testing": {
      "pinned_facts": [
        "Use pytest as the canonical test runner."
      ]
    }
  },
  "preserve_sections": [
    "red lines"
  ]
}

Supported feedback keys are intentionally narrow in 0.7.0:

• sections.<name>.prepend_notes
• sections.<name>.pinned_facts
• preserve_sections

In normal update mode, preserve_sections acts like an implicit exclusion list. In --force mode, those preservation hints are ignored so the command can produce a true clean-slate rebuild.

---

Repository Structure

README.md           # user-facing overview and contributor workflow
AGENTS.md           # conventions for this repository itself
SYSTEM.md           # synthesis spec for generated AGENTS.md files
SKILL.md            # operational workflow used by the skill
pyproject.toml      # packaging, CLI entrypoint, tool configuration
LICENSE
agentskill/
  main.py           # packaged CLI entry point — subcommand dispatch only
  commands/         # analyzer implementations
  lib/              # orchestration, output, update, generation helpers
  common/           # shared low-level helpers and registries
scripts/
  *.py              # thin wrappers that import packaged analyzer entrypoints
tests/              # pytest suite for package code and wrapper behavior
references/
  GOTCHAS.md        # extraction and synthesis errors to avoid
examples/
  README.md             # language fixture index for analyzer validation
  python/               # compact per-language analyzer fixtures
  javascript/
  typescript/
  go/
  rust/
  java/
  kotlin/
  csharp/
  c/
  cpp/
  ruby/
  php/
  swift/
  objectivec/
  bash/
  mixed/
  SINGLE_LANGUAGE.md   # reference output: single-language repo
  MULTI_LANGUAGE.md    # reference output: multi-language single repo
  MONOREPO.md          # reference output: monorepo with multiple services

---

Where Code Goes

• Put packaged CLI and runtime code in agentskill/.
• Put analyzer implementations in agentskill/commands/.
• Put shared orchestration, generation, update, and output helpers in agentskill/lib/.
• Put reusable low-level helpers and registries in agentskill/common/.
• Keep scripts/ limited to thin wrappers and operator-facing workflow entrypoints.
• Do not add analyzer or business logic to scripts/.
• Add tests in tests/ as test_<subject>.py; do not colocate tests under scripts/.
• Keep root-level files focused on metadata, docs, and project-wide specs.

There is no separate steady-state runtime under scripts/, and there is no root cli.py compatibility entrypoint to extend. New runtime behavior should land in the package tree and then be exposed through agentskill.main if it belongs on the public CLI.

---

Developer Workflow

For normal use and contributor verification:

python -m pip install -e '.[dev]'
agentskill analyze <repo> --pretty
ruff format .
ruff check .
mypy
pytest

When you add or extend functionality:

• Add analyzer logic in agentskill/commands/ when it maps to a command.
• Add shared helpers in agentskill/lib/ or agentskill/common/, based on whether they are orchestration-level or low-level utilities.
• Wire new CLI behavior through agentskill/main.py.
• Add a scripts/*.py wrapper only when direct operator or skill invocation is still useful, and keep it as a thin import-and-dispatch shim.
• Cover both packaged behavior and any retained wrapper behavior in tests/.

For retained wrappers:

• Use agentskill <command> ... as the canonical interface in docs and examples.
• Use python scripts/<name>.py ... only for direct analyzer wrappers that still exist.
• Do not add generate or update logic to scripts/; those belong to the packaged CLI.

---

File Ecosystem

Three files govern behavior. Read all three before modifying anything.

File	Role
SYSTEM.md	The canonical spec: what every section of AGENTS.md must contain and how to evaluate it
SKILL.md	The operational workflow: when to invoke, what scripts to run, in what order
GOTCHAS.md	Extraction and synthesis errors from previous runs — read before writing

The public commands stay the same after refactors. The packaged runtime lives under agentskill/, while scripts/ stays intentionally small as a wrapper and operator layer for direct analyzer entrypoints.

---

Examples

The examples/ directory now serves two roles:

• Compact static language fixtures under per-language subdirectories for analyzer validation.
• Reference AGENTS.md examples in SINGLE_LANGUAGE.md, MULTI_LANGUAGE.md, and MONOREPO.md.

If this skill was downloaded from ClawHub, or if examples/ is not present in the local copy, do not consult it; skip that step to avoid execution errors.

See examples/README.md for the supported fixture set.

---

License

MIT