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 and mark gaps as TODO-
--jsonOutput result as JSON instead of writing files-

​
Description

Generates AGENTS.md files or Agent Skills from the built graph. These outputs help coding assistants understand service metadata, owned paths, downstream relationships, APIs, and graph-aware workflows. The command uses:
  • top-level service metadata from devgraph-service, devgraph-api, and devgraph-env
  • hybrid graph ownership data from knowledgeGraph
  • graph analysis questions and coverage gaps from knowledgeGraph.analysis
  • filesystem landmarks such as src/, app/, lib/, components/, and tests/
  • commands inferred from package metadata when available
Generated guidance now points agents to the two main analysis surfaces first:
  • .devgraph/GRAPH_REPORT.md
  • devgraph query "<question>"

​
Examples

Generate agents for all services: 
devgraph agents
Generate for a specific service with directory inference: 
devgraph agents --service api-gateway --service-path ./packages
Use best-effort mode for incomplete graphs: 
devgraph agents --best-effort

​
AGENTS.md Output

Each generated AGENTS.md includes:
  • service commands
  • dependencies and consumers
  • APIs and environment variables
  • owned paths and neighboring files when available
  • graph-aware instructions to read GRAPH_REPORT.md and use devgraph query

​
Agent Skills Format

Use --format skills to generate Agent Skills: 
devgraph agents --format skills

​
Output Structure

.skills/
├── orchestrating-devgraph-context/
│   ├── SKILL.md
│   └── references/
│       └── HANDOFF_TEMPLATE.md
├── querying-architecture/
│   ├── SKILL.md
│   └── references/
│       ├── ARCHITECTURE.md
│       └── SERVICES.md
└── services/
    ├── api-gateway-context/
    │   ├── SKILL.md
    │   └── references/
    │       └── ROUTES.md
    └── user-service-context/
        └── SKILL.md
The overview skill tells agents to:
  • read .devgraph/GRAPH_REPORT.md before broad architecture searches
  • prefer devgraph query "<question>" for focused retrieval
  • use service-specific skills when they need commands, APIs, or owned paths

​
Orchestration Skill

The orchestrating-devgraph-context skill helps one agent gather repo context and hand it to another agent without starting from scratch. It tells agents to:
  • read .devgraph/GRAPH_REPORT.md
  • choose 3 to 6 focused questions from graph analysis, coverage gaps, services, dependencies, and APIs
  • run devgraph query "<question>" for each selected question
  • ask the user only for missing intent, target service, constraints, or done criteria
  • write a Markdown handoff brief from references/HANDOFF_TEMPLATE.md
The handoff template includes:
  • goal
  • known context
  • graph evidence
  • decisions
  • open questions
  • suggested next agent task

​
Use Cases

  • AI-assisted development
  • onboarding and architecture handoff
  • multi-agent context handoff
  • generated service context from the hybrid graph