Browse documentation

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.

These files add instructions to the assembled prompt in that order. They do not change instruction priority: repository files cannot override product safety rules or the user's request.

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

SourceMaximum UTF-8 size
Each startup instruction or prompt template256 KiB
All startup user, repository, and additional instructions combined1 MiB
Each primary-agent or subagent profile64 KiB
Each skill1 MiB
Each runtime subdirectory instruction256 KiB

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/codemode.md (only when code_mode is enabled), 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 {{operating_system}}, not {{ operating_system }}. Unknown or malformed variables fail immediately with the fragment and offending token.

VariableValid fragmentsValue
{{operating_system}}system.md, tools.md, codemode.md, skills.md, compact.mdmacOS, Linux, Windows, or the operating system is <target_os>.
{{terminal_environment}}Same five fragmentsBounded, comma-separated NAME=value summary of TERM_PROGRAM, TERM, and COLORTERM, without a label, or unspecified.
{{session_id}}Same five fragmentsCurrent durable session ID, or unspecified when no session exists. Child sessions use their own IDs.
{{cwd}}Same five fragmentsWorking directory supplied to the current run, without a label. Child sessions use their own working directories.
{{SKILLS_LIST}}system.md, tools.md, codemode.md, skills.mdEnabled names as - skill-name, optionally followed by : description from trimmed non-empty frontmatter; - none if empty.
{{LIST_SUBAGENTS}}subagents.md onlyIdentity metadata, without profile prompt bodies.

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

Session values are populated before the first provider request. /system-prompt uses the active session and working directory. Values remain fixed during a run; literal placeholder text inside inserted values or instruction files is not expanded again.

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 reports an invalid or unavailable saved ID. Alt-P cycles through None and valid profiles, saving 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.

Skill content returns as tool-result text enclosed in <Skill name="<skill-name>" dir="<path/to/SKILL.md>">...</Skill>. References use file="<path/to/file>" instead of dir. Paths identify the loaded files; dir names the descriptor file, not its parent directory. Attribute values are XML-escaped; full file contents, including frontmatter, remain unchanged inside the wrapper. The same wrapper appears in direct reads and Code Mode files[].text.

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. Enclosed skill and reference contents 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 ↗