Technical documentation / Reference

Instructions, prompts, skills, and primary agents

Feature docs index · Repository README

Use AGENTS.md for shared rules, prompt fragments for assistant guidance, primary-agent profiles for a persona, and skills for instructions loaded on demand. Paths below use the default ~/.magi-code; setting MC_HOME relocates that user directory.

Add project instructions

Startup reads, in order:

1. ~/.magi-code/AGENTS.md.
2. AGENTS.md in the active working directory.
3. Absolute UTF-8 .md files in knowledge.instructions.additional_markdown_paths, in array order. Subagents inherit them.

Additional paths must name readable Markdown files. Relative paths, directories, other extensions, missing/unreadable files, and invalid UTF-8 fail locally before provider requests. Never put API keys, OAuth tokens, bearer headers, account IDs, or private auth output in instructions.

Startup instruction precedence:

product/system defaults < ~/.magi-code/AGENTS.md < active-working-directory AGENTS.md < knowledge.instructions.additional_markdown_paths[] < current user prompt

Enable knowledge.instructions.subdir_discovery: true to load subdirectory AGENTS.md files after tools access paths. It applies to read, view_image, hash_edit, write, list_files, and explicit-path grep, find, and ast_grep, not bash, browser, web/code search, MCP, skills, or subagents. Discovery walks upward nearest-first within the project root, stops before root AGENTS.md, and injects each canonical file once per session as provider-visible transcript/activity context. It is symlink-safe and caps each file at 256 KiB.

Keep local prompt sources within limits

Reads reject oversize or invalid UTF-8 without loading unbounded bodies. Profile and skill files reject direct symlinks; instructions and templates retain their caller-selected symlink behavior.

Override prompt fragments

Assistant templates are assembled before dynamic AGENTS.md content. Bundled defaults are prompts/system.md, prompts/tools.md, prompts/skills.md, and prompts/subagents.md. Override them at ~/.magi-code/prompts/<fragment>.md or $MC_HOME/prompts/<fragment>.md.

Variables are exact and case-sensitive: use {{has_ripgrep}}, not {{ has_ripgrep }}. Unknown or malformed variables fail immediately with the fragment and offending token.

{{TOOLS_LIST}} is unsupported and fails immediately. Runtime facts use bounded local checks, without provider/network calls, credential-file reads, or arbitrary environment variables.

Tool schema descriptions are defined in src/tools/capability.rs and compiled into the binary, not loaded from runtime $MC_HOME files. The normal <Tools> prompt supplies guidance without enumerating definitions.

For /compact, override prompts/compact.md in the same user prompt directory. Keep session history out of it; the runtime supplies replay items separately.

Choose a primary agent

Put UTF-8 profiles in ~/.magi-code/agents/*.md or $MC_HOME/agents/*.md. The filename stem is the stable ID, limited to ASCII letters, digits, _, and -. Frontmatter requires non-empty name and description, followed by a non-empty body:

---
name: TARS
description: Deadpan tactical engineering assistant.
---
You are TARS. Prioritize concise execution, risk control, and evidence-backed verification.

Mission Control restores a valid agent.primary_agent from settings. Otherwise it starts with Agent: None and records a sanitized diagnostic for an invalid or unavailable saved ID. Shift-Tab cycles through None and valid profiles, immediately persisting only the ID or null.

The selected body affects only the main assistant, not subagents. It is appended in this exact form, using the profile name and trimmed body:

<Your-Role Persona=TARS>
You must always follow the instructions of your assigned persona:
You are TARS. Prioritize concise execution, risk control, and evidence-backed verification.
</Your-Role>

Install and use skills

Each skill is <skill-name>/SKILL.md, directly under a discovery root or inside one grouping folder (<folder>/<skill-name>/SKILL.md). Discovery stops there; it does not recurse further.

Roots, from highest to lowest priority for duplicate names:

1. Active cwd .agents/skills.
2. Absolute knowledge.skills.additional_paths entries in settings; later entries win. Relative entries are skipped with diagnostics.
3. ~/.magi-code/skills.

The directory containing SKILL.md defines the skill name and $skill-name tag; frontmatter name cannot override it. Frontmatter description supplies provider-list metadata, not autocomplete insertion.

Discovery keeps the selected path and parsed frontmatter, not the body. Read current content on demand with skill://<name> or skill://<name>/<relative-reference>. Primary reads use one bounded, no-follow handle. Reference reads enforce containment, traversal, file-type, symlink, UTF-8, and size checks.

Repeated unchanged reads may use a compact reference in the provider request when an earlier complete copy is still present. Every explicit read still checks and loads the current target; displayed results and session records retain the full read output. Matching requires the same selected source, snapshot, and selection. Truncated or failed reads do not establish coverage, and compaction or replay truncation cannot leave a reference to missing instructions. Skills and references are never summarized or rewritten.

In Mission Control, type $ anywhere to autocomplete enabled skills. /skills changes future suggestions. The accepted $skill-name tag is ordinary prompt guidance: it does not load a skill automatically or add provider/session metadata.

A top-level argument-hint can show a helper beside the suggestion. It must be a single-line scalar; matching single/double quote wrappers work, but multiline/block YAML does not. Display sanitizes it, collapses it to one line, and limits it to 160 columns. Missing or blank hints show skill. Hints do not change the provider prompt, inserted tag and trailing space, or loading behavior.

Edit this page on GitHub ↗