Kiro Config Guide: Steering Files, AGENTS.md, mcp.json, permissions.yaml

Kiro calls instructions "steering": markdown files in .kiro/steering/ (workspace) and ~/.kiro/steering/ (global) with inclusion modes. It also reads AGENTS.md at the workspace root and in the global steering folder, and always includes it. MCP servers are in .kiro/settings/mcp.json or ~/.kiro/settings/mcp.json, hooks in .kiro/hooks/, skills in .kiro/skills/. Permissions are capability rules (deny > ask > allow) in ~/.kiro/settings/permissions.yaml, and a cloned repo cannot inject them.

Kiro at a glance

Global instructions	✓ Yes `~/.kiro/steering/*.md` (AGENTS.md allowed there)
Project instructions	✓ Yes `.kiro/steering/*.md` with inclusion modes; `AGENTS.md` at root
Nested / subfolder	? Not documented Not documented
AGENTS.md	✓ Yes Always included (no inclusion modes)
Skills (SKILL.md)	✓ Yes `.kiro/skills/` (workspace), `~/.kiro/skills/` (global)
MCP config	✓ Yes `.kiro/settings/mcp.json` (workspace), `~/.kiro/settings/mcp.json` (user)
Permissions / allowlist	✓ Yes Capability rules (`shell`, `fs_read`, `fs_write`, `web_fetch`, `mcp`) with deny > ask > allow in `~/.kiro/settings/permissions.yaml`
Sandbox	◐ Partial Kiro on the web runs in an isolated cloud sandbox; local sandbox not detailed
Hooks	✓ Yes `.kiro/hooks/` (file events, tool events)
Claude Pro/Max login	✕ No Not supported
ChatGPT Plus/Pro login	✕ No Not supported
API key / own plan	✕ No Kiro plans; sign in with GitHub, Google, AWS Builder ID or IAM Identity Center

Exact file paths

Path	Scope	What it does
`.kiro/steering/*.md`	Workspace	Steering with inclusion modes
`~/.kiro/steering/`	User	Global steering, AGENTS.md allowed
`AGENTS.md`	Workspace	Always-included steering
`.kiro/settings/mcp.json`	Workspace	MCP servers (user: ~/.kiro/settings/mcp.json)
`~/.kiro/settings/permissions.yaml`	User	Permission rules
`.kiro/hooks/`	Workspace	Hooks
`.kiro/skills/<name>/SKILL.md`	Workspace	Skills

Using a shared AGENTS.md with Kiro

Native: always included as steering. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

Workspace MCP server

File: .kiro/settings/mcp.json

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Safe permissions preset

Safe Kiro permissions

File: ~/.kiro/settings/permissions.yaml

rules:
  - capability: fs_read
    effect: allow
  - capability: shell
    match: ["git status*", "git diff*", "npm test*"]
    effect: allow
  - capability: shell
    match: ["git push*"]
    effect: ask
  - capability: shell
    match: ["rm -rf *", "sudo *", "git push --force*", "git reset --hard*", "terraform destroy*"]
    effect: deny
  - capability: fs_write
    match: ["**/.env", "**/*.pem", "**/*.key"]
    effect: deny

Deny always wins, regardless of scope. Rules live outside the repo, so a cloned project can't grant itself permissions.

Gotchas

AGENTS.md has no inclusion modes; it is always loaded, so keep it short and move scoped guidance into steering files.
On Kiro web, your local ~/.kiro/steering is not available automatically.

FAQ

Does Kiro support AGENTS.md?

Yes. Kiro reads AGENTS.md at the workspace root and in ~/.kiro/steering/, and always includes it as steering.

Where is the Kiro MCP config?

.kiro/settings/mcp.json in the workspace and ~/.kiro/settings/mcp.json for all workspaces.

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

Kiro configuration guide: instruction files, MCP, permissions