# Exporting to agent rule formats

SharkCraft's source of truth is its structured knowledge + MCP server. But
many tools still read flat markdown files. `shrk export` renders a
compatibility view of your project's rules / paths / agent actions in one of
several common formats.

## Supported formats

| Format | Default output path | Audience |
|---|---|---|
| `agents-md` | `AGENTS.md` | General-purpose agent rule file. |
| `claude-md` | `CLAUDE.md` | Claude Code (claude.ai/code) project instructions. |
| `cursor-rules` | `.cursor/rules/sharkcraft.mdc` | Cursor IDE MDC rules. |
| `copilot-instructions` | `.github/copilot-instructions.md` | GitHub Copilot. |

## Usage

```bash
# Preview (default: dry-run)
shrk --cwd <repo> export claude-md

# Save to the default path for that format
shrk --cwd <repo> export claude-md --write

# Save to a custom path
shrk --cwd <repo> export agents-md --write --output ./docs/AGENTS.md

# Scope the export to a task
shrk --cwd <repo> export claude-md --task "generate a service"

# Bound the size
shrk --cwd <repo> export agents-md --max-rules 8 --max-paths 5
```

## What's in the exported file

- Project header (`name` + `description` from `sharkcraft.config.ts`).
- **Rules to follow** — top N rules by priority, with the entry id + summary.
- **Where files belong** — top N path conventions with the canonical folder.
- **Agent actions** — aggregated `actionHints` across all entries:
  recommended MCP tools, CLI commands, forbidden actions, verification
  commands.
- **Pipelines** — a list of available declarative workflows so the agent can
  call `shrk pipelines get <id>` for full step lists.

All exports start with a `> Generated by` preamble that points readers back
to the SharkCraft source of truth.

## Trade-offs

- Exports are intentionally short — flat markdown can't represent the full
  context that MCP serves. Treat them as compatibility shims, not
  replacements.
- Exports are **regenerated on demand**. Don't hand-edit them; edit the
  underlying SharkCraft knowledge and re-run `shrk export`.
- The export does NOT include `git`/CI rules, environment variables, or any
  secret. It only renders structured SharkCraft knowledge.

## When to use each format

- **CLAUDE.md** — paired with the SharkCraft MCP server for Claude Code.
  CLAUDE.md acts as the boot brief; the MCP server is the live data source.
- **AGENTS.md** — neutral fallback for clients that read AGENTS.md.
- **Cursor rules** — when Cursor users want the project rules without
  installing the MCP server.
- **Copilot instructions** — when the team uses GitHub Copilot as the
  primary surface.