https://github.com/airscripts/agentskill
Analyze a code repository and synthesize an AGENTS.md.
https://github.com/airscripts/agentskill
agents ai cli python skill
Last synced: about 1 month ago
JSON representation
Analyze a code repository and synthesize an AGENTS.md.
- Host: GitHub
- URL: https://github.com/airscripts/agentskill
- Owner: airscripts
- License: mit
- Created: 2026-04-24T23:35:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T23:17:02.000Z (about 1 month ago)
- Last Synced: 2026-04-29T02:02:54.969Z (about 1 month ago)
- Topics: agents, ai, cli, python, skill
- Language: Python
- Homepage: https://airscript.it
- Size: 436 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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`](./SYSTEM.md).
---
## Install
```bash
pip install -e .
```
For local development:
```bash
python -m pip install -e '.[dev]'
```
To enable the commit-time checks after installing the dev environment:
```bash
pre-commit install
```
---
## Development Checks
Run the baseline quality checks locally:
```bash
ruff format .
ruff check .
mypy
pytest
```
To verify without changing files:
```bash
ruff format --check .
ruff check .
mypy
pytest
```
To run the commit-time hooks across the full repository:
```bash
pre-commit run --all-files
```
The pre-commit setup runs Ruff formatting, Ruff linting, and mypy before each
commit. Full `pytest` runs remain part of normal local verification and CI,
rather than a default commit-time hook.
---
## Usage
```bash
# Run all scripts and synthesize a report
python cli.py analyze --pretty
# Run individual scripts
python cli.py scan --pretty
python cli.py measure --lang python --pretty
python cli.py config --pretty
python cli.py git --pretty
python cli.py graph --pretty
python cli.py symbols --pretty
python cli.py tests --pretty
# Write output to file
python cli.py analyze --out report.json
# Run a script directly
python scripts/scan.py --pretty
```
---
## Repository Structure
```
cli.py # unified entry point — subcommand dispatch only
pyproject.toml # build metadata and entry point declaration
SYSTEM.md # behavioral spec for AGENTS.md generation — never modify
SKILL.md # operational workflow — never modify
AGENTS.md # conventions for this repo itself
scripts/
commands/
scan.py # directory tree walk, file inventory, read order
measure.py # indentation, line lengths, blank lines, trailing whitespace
config.py # formatter/linter/type-checker detection from config files
git.py # commit log parsing, branch analysis, merge strategy
graph.py # internal import graph, cycle detection, monorepo detection
symbols.py # symbol name extraction and naming pattern clustering
tests.py # test-to-source mapping, framework detection, fixture extraction
lib/
runner.py # aggregate analyzer orchestration for `analyze`
output.py # shared JSON output helpers for CLI and scripts
common/
constants.py # shared repository-walk constants
fs.py # shared low-level filesystem helpers
scan.py # thin wrapper for direct script execution
measure.py # thin wrapper for direct script execution
config.py # thin wrapper for direct script execution
git.py # thin wrapper for direct script execution
graph.py # thin wrapper for direct script execution
symbols.py # thin wrapper for direct script execution
tests.py # thin wrapper for direct script execution
references/
GOTCHAS.md # extraction and synthesis errors to avoid
examples/
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
```
---
## 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. Internal code is organized by technical role: analyzers in `scripts/commands/`, shared CLI infrastructure in `scripts/lib/`, and low-level helpers in `scripts/common/`.
---
## Examples
The `examples/` directory contains three reference `AGENTS.md` files, each representing a distinct repo shape:
- **`SINGLE_LANGUAGE.md`** — a Go HTTP service with no external tooling
- **`MULTI_LANGUAGE.md`** — a Python/TypeScript project with shared conventions
- **`MONOREPO.md`** — a multi-service monorepo with per-service sections
Consult the relevant example before handling an unfamiliar repo shape.
---
## License
MIT