# How to Generate AI Agent Documentation with `astryx init --features agents`

> Generate AI agent documentation with astryx init --features agents. Quickly create component indexes, behavioral rules, and CLI references for AI coding assistants.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**The `astryx init --features agents` command generates concise AI agent documentation files—such as [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/CLAUDE.md), or `.cursorrules`—that provide AI coding assistants with component indexes, behavioral rules, and CLI references needed to produce correct XDS component code.**

The **facebook/astryx** CLI ships with a built-in *agent-docs* generator designed to create the reference files necessary for AI coding assistants to generate valid XDS components. When you invoke `astryx init --features agents`, the tool assembles a curated knowledge base containing component definitions, prohibited patterns, and CLI shortcuts. These files are deliberately compact (approximately 2 KB) and marked with `XDS` comment delimiters so AI systems can locate relevant sections instantly.

## How the Agent Documentation Generator Works

The generation logic is integrated into the `init` command flow at `packages/cli/src/commands/init.mjs`. When the **agents** feature is selected, the CLI parses the `--agent` and `--agent-docs-path` arguments (lines 71-80) and delegates the actual file creation to the `installAgentDocs` helper function.

### The `installAgentDocs` Implementation

The core assembly logic resides in `packages/cli/src/commands/agent-docs.mjs`. This module constructs the documentation by compiling three essential sections:

- **Component index** – A searchable registry of all available components, their import paths, and prop definitions.
- **Behavioral rules** – Strict prohibitions such as "no raw `<div>` elements" and "no inline `style` attributes" that enforce XDS conventions.
- **CLI quick-reference** – A trimmed command reference including `astryx component --list` and `astryx template` for easy copy-pasting into AI prompts.

Once assembled, the write routine creates the target file (e.g., [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/CLAUDE.md), or `.cursorrules`) and prints a success message: `✓ AI agent docs installed → …`.

### Path Safety and Error Handling

When specifying custom output locations via `--agent-docs-path`, the CLI validates path safety using the logic in `packages/cli/src/lib/path-safety.mjs`. If the target path is deemed unsafe (e.g., points outside the project root or to a protected system directory), the command throws a `PathSafetyError` with a clear, actionable message (lines 88-98).

## Generating Documentation for Different AI Agents

The `astryx init` command supports multiple AI agent formats through the `--agent` flag. Each target produces a file optimized for that specific assistant's context window and rule structure.

Generate the default agent documentation:

```bash
npx astryx init --features agents

```

Target a specific AI assistant:

```bash
npx astryx init --features agents --agent claude
npx astryx init --features agents --agent cursor
npx astryx init --features agents --agent codex

```

These commands create [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/CLAUDE.md), `.cursorrules`, or [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md) respectively, each containing the same core XDS knowledge formatted for the target AI.

## Customizing Output Paths

By default, files are written to the project root. Use `--agent-docs-path` to install documentation to arbitrary locations, such as Cursor's user rules directory:

```bash
npx astryx init --features agents \
  --agent-docs-path ~/.cursor/rules/xds.mdc

```

This is particularly useful when managing global AI rules or organizing documentation outside the repository root.

## Non-Interactive Mode and CI Integration

The CLI detects interactive versus automated environments via `packages/cli/src/utils/interactive.mjs`. When running in non-interactive mode (such as CI pipelines), the command skips prompts, installs the docs silently, and exits with status code 0.

For scripted automation or CI pipelines, combine the `--json` flag for machine-readable output:

```bash
npx astryx init --features agents --agent codex --json

```

This ensures the command completes without hanging on input requests and provides structured output for downstream processing.

## Keeping Documentation Current

After upgrading the Astryx CLI to a new version, re-running `astryx init --features agents` updates the agent documentation in place. This synchronizes the AI's knowledge base with any new components, changed prop signatures, or updated behavioral rules introduced in the latest release.

For a comprehensive guide on integrating these files into your AI workflow, see the documentation source at `packages/cli/docs/working-with-ai.doc.mjs` (lines 27-55), which covers CLI installation and agent-docs invocation in detail.

## Summary

- **`astryx init --features agents`** invokes the `installAgentDocs` helper in `packages/cli/src/commands/agent-docs.mjs` to generate AI-specific documentation.
- Generated files include **component indexes**, **behavioral prohibitions**, and **CLI quick-references**, wrapped in `XDS` comment delimiters for rapid AI parsing.
- Use **`--agent`** to target specific formats (Claude, Cursor, Codex) and **`--agent-docs-path`** to customize the installation location.
- The CLI validates custom paths via `path-safety.mjs`, throwing `PathSafetyError` for unsafe destinations.
- Non-interactive mode (detected via `interactive.mjs`) supports CI automation with the **`--json`** flag.

## Frequently Asked Questions

### What files does `astryx init --features agents` generate?

The command generates context files for AI assistants, typically named [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/CLAUDE.md), or `.cursorrules` depending on the `--agent` flag specified. These files contain approximately 2 KB of structured data including component indexes, XDS behavioral rules, and CLI references.

### How do I generate documentation for a specific AI agent like Claude or Cursor?

Pass the `--agent` flag followed by the target agent name. For example, `npx astryx init --features agents --agent claude` creates [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/CLAUDE.md), while `--agent cursor` generates `.cursorrules` in the project root. Omitting the flag defaults to the standard [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md) format.

### Can I specify a custom location for the agent documentation files?

Yes. Use the `--agent-docs-path` argument to define an absolute or relative path. For example, `npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc` installs the rules directly into Cursor's global configuration. The CLI validates the path using `PathSafetyError` handling to prevent unsafe writes.

### How does the command handle errors or unsafe file paths?

If `--agent-docs-path` points to a restricted or unsafe directory, the CLI catches the error as `PathSafetyError` (defined in `packages/cli/src/lib/path-safety.mjs`) and reports a clear failure message without writing any files. In non-interactive mode, this error is returned as a JSON object when using the `--json` flag.