YAML Frontmatter

AGENTS.md supports optional YAML frontmatter for agent configuration: permissions, guardrails, and metadata.

Schema

---
agent:
  name: string           # Agent identifier
  purpose: string        # Human-readable purpose
  model: string          # AI model (gpt-4o-mini, claude-3-sonnet)
  triggers: string[]     # pull_request.opened, push, etc.
  permissions:           # Permission boundaries
    shell:
      allow: string[]    # Allowed commands (supports *)
      deny: string[]     # Denied commands
      default: allow|deny
    pull_requests: read|write|none
    issues: read|write|none
  guardrails: string[]   # "Never modify code", "Never merge"
  metadata: Record       # Custom key-value
---

Example

---
agent:
  name: pr-labeler
  purpose: "Apply size labels to PRs"
  model: gpt-4o-mini
  triggers: [pull_request.opened]
  permissions:
    shell:
      allow: ["pnpm test", "pnpm lint"]
      default: deny
  guardrails:
    - "Never modify code, never merge"
---

## Build
`pnpm run build`

## Test
`pnpm test`

Shell Permissions

When shell.allow is set, only listed commands (or wildcard matches) can execute. When shell.default: deny, any command not in allow is blocked.

allow: ["pnpm *"] — Allow any pnpm command
deny: ["rm -rf"] — Block even if otherwise allowed

Flat vs Nested

Both structures are supported:

# Nested
---
agent:
  name: my-agent
---

# Flat (legacy)
---
name: my-agent
---

→ Execution & Safety