A CLI tool that scans your backend source code and automatically generates Action Catalogs and Agent Skill directories — structured metadata that enables AI agents to discover, understand, and invoke your APIs.
No manual annotation required. Point aak at your project, and it produces machine-readable catalogs or Agent Skills-compliant skill directories with route paths, HTTP methods, parameters, authentication schemes, risk levels, and JSON Schema — ready for any LLM orchestration layer to consume.
Your Backend Codebase
(TypeScript / Python / Go — any framework)
│
▼
┌──────────────────────────┐
│ aak scan │
│ │
│ 1. Discover source files │
│ 2. Incremental cache │──▶ .aak-cache.json
│ (skip unchanged) │
│ 3. tree-sitter AST parse │
│ (parallel via rayon) │
│ 4. Extract routes, │
│ params, auth, scheme │
│ 5. Infer action metadata │
│ (id, title, risk, │
│ JSON Schema) │
│ 6. Validate │
└────────────┬─────────────┘
│
┌────────────┴─────────────┐
▼ ▼
actions.catalog.json api-catalog.json
(Action-level metadata) (Route-level detail)
│ │
▼ ▼
┌───────────────────────────────────────────┐
│ LLM / AI Agent Layer │
│ │
│ • Read catalog to discover available │
│ actions and their input schemas │
│ • Select action + build params │
│ • Call your API with confidence │
└───────────────────────────────────────────┘
── or ──
┌──────────────────────────┐
│ aak skill │
│ │
│ Converts scan results │
│ into Agent Skills spec │
│ (progressive disclosure) │
└────────────┬─────────────┘
│
┌────────────┴─────────────┐
▼ ▼
SKILL.md references/*.md
(YAML frontmatter + (Full endpoint docs:
quick reference table) params, auth, examples)
Download a prebuilt binary from the Releases page, or build from source:
cargo install --path crates/aak-cliaak scan ./my-backend-projectThat's it. Two files are generated in ./.aak/actions/:
| File | Description |
|---|---|
actions.catalog.json |
Action-level catalog for AI agents (id, title, risk, input schema) |
api-catalog.json |
Route-level catalog with full param details, auth info, source paths |
Next.js App Router routes (
app/api/**/route.ts) are detected automatically — no extra flags needed. If your project uses the legacy Pages Router, pass--nextjs-page(or setfile_router.pages_router: truein config) to enable Pages Router detection.
# Filter by language
aak scan ./my-project --lang go
# Force full scan (ignore incremental cache)
aak scan ./my-project --full
# Custom output directory
aak scan ./my-project --out-dir ./output# Generate an Agent Skills-compliant skill directory
aak skill ./my-backend-project --name my-api
# With base URL and language filter
aak skill ./my-project --name my-api --base-url https://api.example.com --lang typescript
# Custom output directory
aak skill ./my-project --name my-api --out-dir ./outputThis generates a skill directory:
skill/my-api/
├── SKILL.md # YAML frontmatter + API overview + quick reference table
└── references/
├── users.md # Full endpoint docs for /api/users
└── orders.md # Full endpoint docs for /api/orders
The output follows the Agent Skills specification with progressive disclosure: name + description loaded at startup → SKILL.md body loaded on activation → references/ loaded on demand.
# Generate default config file
aak init
# Validate an existing catalog
aak validate --catalog ./actions.catalog.json| Language | Frameworks | Detection |
|---|---|---|
| TypeScript/JS | Express, Nest.js, Hono | Method calls (router.get), decorators (@Get) |
| TypeScript/JS | Next.js App Router | File-based routing (app/api/**/route.ts) |
| Python | FastAPI, Flask | Decorators (@app.get, @app.route) |
| Go | Gin, Chi, net/http | Method calls (r.GET, r.Get, http.HandleFunc) |
The scanner uses generic AST patterns — unlisted frameworks using similar conventions will often work automatically.
When auth middleware or decorators are detected, aak infers the specific authentication scheme and header:
| Source Keywords | Scheme | Header | Usage Example |
|---|---|---|---|
jwt, bearer, HTTPBearer, JWTAuth |
bearer | Authorization | Authorization: Bearer <token> |
apiKey, api_key, x-api-key |
api-key | X-API-Key | X-API-Key: <key> |
basic, BasicAuth, httpBasic |
basic | Authorization | Authorization: Basic <base64> |
oauth, OAuth2 |
oauth2 | Authorization | Authorization: Bearer <token> |
session, cookie, sessionAuth |
cookie | Cookie | Cookie: session=<value> |
Language-specific heuristics also apply:
- Python:
Depends(get_current_user)/Security(→ bearer;login_required→ cookie - Go:
authMiddleware/JWTAuth/TokenAuth→ bearer
{
"version": "1.0",
"count": 3,
"actions": [
{
"id": "users.get",
"title": "List user",
"risk": "low",
"page": "routes.users"
},
{
"id": "users.create",
"title": "Create user",
"risk": "medium",
"input_schema": {
"type": "object",
"properties": {
"name": { "type": "string", "x-param-location": "body" },
"email": { "type": "string", "x-param-location": "body" }
},
"required": ["name", "email"]
}
},
{
"id": "users.delete",
"title": "Delete user",
"risk": "high",
"confirm": true,
"input_schema": {
"type": "object",
"properties": {
"id": { "type": "string", "x-param-location": "path" }
},
"required": ["id"]
}
}
]
}---
name: my-backend-api
description: "Backend API with 6 endpoints covering users, orders."
---
# My Backend Api
This API provides 6 endpoints across 2 resources.
## Quick Reference
| Action | Method | Path | Risk |
|--------|--------|------|------|
| List user | GET | /api/users | low |
| Create user | POST | /api/users | medium |
| Get user | GET | /api/users/:id | low |
| Delete user | DELETE | /api/users/:id | high |
| List order | GET | /api/orders | low |
| Create order | POST | /api/orders | medium |
## Authentication
| Scheme | Header | Usage |
|--------|--------|-------|
| bearer | Authorization | `Authorization: Bearer <token>` |
## Detailed Documentation
For complete parameter details and examples, see:
- [Users API](references/users.md)
- [Orders API](references/orders.md)Scan the target directory, extract API routes, and generate action catalogs.
| Option | Type | Default | Description |
|---|---|---|---|
<TARGET> |
required (positional) | — | Target directory to scan |
--out-dir <DIR> |
optional | ./.aak/actions |
Output directory for generated catalogs |
--catalog-mode <MODE> |
optional | single |
Catalog output mode: single (one file) or sharded (split into multiple files) |
--format <FORMAT> |
optional | json |
Output format: json or yaml |
--lang <LANG> |
optional | all | Restrict scanning to a specific language: typescript, python, or go |
--nextjs-page |
flag | off | Enable Next.js Pages Router detection (App Router is detected automatically) |
--full |
flag | off | Force a full scan, ignoring the incremental cache (.aak-cache.json) |
Exit codes: 0 success, 1 error, 3 scan completed but no routes found.
Scan the target directory, extract API routes, and generate an Agent Skills-compliant skill directory with SKILL.md and references/*.md.
| Option | Type | Default | Description |
|---|---|---|---|
<TARGET> |
required (positional) | — | Target directory to scan |
--name <NAME> |
optional | inferred from directory name | Skill name (lowercase letters + hyphens, e.g. my-api) |
--out-dir <DIR> |
optional | <TARGET>/.aak/skill |
Output directory; skill files go into <OUT_DIR>/skill/<NAME>/ |
--base-url <URL> |
optional | — | API base URL to include in generated docs |
--lang <LANG> |
optional | all | Restrict scanning to a specific language: typescript, python, or go |
--nextjs-page |
flag | off | Enable Next.js Pages Router detection (App Router is detected automatically) |
--full |
flag | off | Force a full scan, ignoring the incremental cache |
Exit codes: 0 success, 1 error, 3 scan completed but no routes found.
Generate a default aak.config.yaml configuration file in the current directory. Exits with an error if the file already exists.
No additional options.
Validate an existing catalog file against the action schema and validation rules.
| Option | Type | Description |
|---|---|---|
--catalog <PATH> |
required | Path to the catalog JSON file to validate |
Prints the number of valid actions on success, or lists each validation error on failure.
Create aak.config.yaml or aak.config.toml in your project root. YAML takes priority if both exist.
version: "1.0"
scan:
target: "."
exclude:
- node_modules
- __pycache__
- vendor
- .venv
- target
output:
dir: "./.aak/actions"
catalog_mode: "single" # single | sharded
format: "json"
file_router:
enabled: true # App Router detection (default: on)
pages_router: false # Pages Router detection (default: off)Single binary, no runtime dependencies. Benchmarked on synthetic files (mixed TS/Python/Go):
| Files | Time |
|---|---|
| 100 | ~183ms |
| 500 | ~849ms |
| 1000 | ~1.85s |
crates/
├── aak-core Core types, inference engine, validator
├── aak-parser tree-sitter AST parsing + language scanners
├── aak-scanner Orchestrator, file walker, incremental cache
├── aak-generator Catalog + Agent Skill output generation
├── aak-config Config file loading (YAML/TOML)
└── aak-cli CLI entry point (clap)
cargo test --workspace # 127 tests
cargo clippy --workspace # lint
cargo fmt --all # format
cargo bench -p aak-scanner # benchmark
cargo build --release -p aak-cli # buildMIT