Project files (.magic)

Per-project state lives in <workspace>/.magic/ — a directory at the workspace root. Today, two things live here that you’ll author yourself:

<workspace>/
└── .magic/
    ├── skills/             # Project-local skills (each under <name>/SKILL.md)
    └── rules/              # Project-local Markdown rules (under <category>/<name>.md)

If .magic/ doesn’t exist yet, create it (or its skills/ and rules/ subdirectories) the first time you author one. Magic Coder discovers them on session start.

Skills

Project-local Skills appear as slash commands in Magic Coder when the workspace is trusted. Each skill is a Markdown file at <workspace>/.magic/skills/<name>/SKILL.md. See Skills for the format.

Rules

Project-local Rules are short Markdown documents the agent reads as guidance — code-review checklists, release procedures, domain notes. Each rule lives at <workspace>/.magic/rules/<category>/<name>.md. See Rules for the format and the always_apply flag.

Trust gates project-local content

skills/ and rules/ are loaded only when the workspace is trusted. Until trust is granted, project-local content is ignored. See Workspaces & trust.

This is intentional: opening Magic Coder against an unfamiliar repo (auditing a PR, exploring a dependency) shouldn’t automatically grant that repo’s authored content access to your session.

Sharing with your team

Commit <workspace>/.magic/skills/ and <workspace>/.magic/rules/ to source control like any other code. Magic Coder reads from the same on-disk path on every developer’s machine — no install step needed.

Command permissions

Persistent allow/deny decisions for shell commands are managed through the Command permissions approval flow. The persistent format is being reworked — for now, use the prompt’s “approve & remember” / “deny & remember” choices to record decisions, and the runtime takes care of remembering.

Other things in .magic

If you see files in .magic/ outside skills/ and rules/, they’re either:

• Created by other tools (some teams put their own state in .magic/), or
• Future Magic Coder additions that haven’t shipped yet.

Magic Coder will not touch files it didn’t create.