Skip to main content

​
Usage

devgraph agents [options]

​
Options

OptionDescriptionDefault
--graph <path>Path to graph.json.devgraph/graph.json
--out-dir <dir>Output directory.devgraph/agents
--service <name>Generate for a specific service only-
--service-path <path>Base path to service directories for inference-
--format <format>Output format: agents or skillsagents
--best-effortGenerate even with missing data (mark as TODO)-
--jsonOutput result as JSON instead of writing files-

​
Description

Generates rich AGENTS.md files for each service in your graph. These files help AI coding assistants (like Claude, Cursor, Copilot) understand your services better by providing context about commands, dependencies, APIs, and codebase structure. The command automatically infers information from:
  • package.json scripts: dev, build, test, start, lint
  • Lockfiles: Detects package manager (npm, pnpm, yarn, bun)
  • Filesystem landmarks: src/, app/, lib/, components/, tests/, etc.

​
Examples

Generate agents for all services: 
devgraph agents
Output: 
Generated 3 AGENTS.md files:

  .devgraph/agents/api-gateway.md
  .devgraph/agents/user-service.md
  .devgraph/agents/product-service.md
Generate for a specific service with inference from its directory: 
devgraph agents --service api-gateway --service-path ./packages
This reads ./packages/api-gateway/package.json to infer commands. Use best-effort mode for incomplete graphs: 
devgraph agents --best-effort
Generates files even when some data is missing, marking gaps as TODO.

​
Output Format

Each generated AGENTS.md includes: 
# api-gateway

## Quick Reference
- **Type**: node
- **Package Manager**: pnpm

## Commands
| Task | Command |
|------|---------|
| dev | pnpm dev |
| build | pnpm build |
| test | pnpm test |

## Dependencies
- postgres (database)
- user-service (node)

## APIs Consumed
- user-service: GET /users/:id, POST /users

## Key Directories
- `src/` - Source code
- `tests/` - Test files

## Search Terms
api-gateway, gateway, routing

​
Agent Skills Format

Use --format skills to generate Agent Skills — the open standard supported by Claude Code, Cursor, Gemini CLI, VS Code, GitHub Copilot, and 25+ other tools. 
devgraph agents --format skills
Output: 
Generated 6 skill file(s):
  - querying-architecture/SKILL.md
  - querying-architecture/references/ARCHITECTURE.md
  - querying-architecture/references/SERVICES.md
  - services/api-gateway-context/SKILL.md
  - services/api-gateway-context/references/ROUTES.md
  - services/user-service-context/SKILL.md

Output written to: .skills

​
Output Structure

.skills/
├── querying-architecture/          # Overview skill
│   ├── SKILL.md                    # CLI commands + when to use them
│   └── references/
│       ├── ARCHITECTURE.md         # Full dependency graph
│       └── SERVICES.md             # Quick-reference index
└── services/                       # Per-service skills
    ├── api-gateway-context/
    │   ├── SKILL.md                # Commands, deps, consumers
    │   └── references/
    │       └── ROUTES.md           # API route definitions
    └── user-service-context/
        └── SKILL.md
The overview skill teaches agents how to query the architecture using CLI commands (devgraph impact, devgraph validate, devgraph run). Per-service skills provide commands, dependencies, downstream consumers, API routes, and key directories for each service. Skills use progressive disclosure — agents load only the name and description at startup (~100 tokens), then read the full skill body only when the task is relevant.

​
Use Cases

AI-assisted development: Drop AGENTS.md or Agent Skills files in your repo so AI tools understand your services. Onboarding: New developers can quickly understand how to work with each service. Documentation: Auto-generate baseline documentation from your devgraph blocks.