Skills

The skills teach the magus tool surface: query the graph instead of grepping, run work through targets instead of raw tools, triage generated files, ground a refactor in graph evidence. They never mention workspace specifics, so they go stale only when the tool surface changes - and that staleness is detectable.

One shared source is embedded in the binary in the cross-agent Agent Skills format (a SKILL.md with name and description frontmatter). Every destination receives identical bytes. Naming the directory your host reads is the only host-specific step, and there are no per-model bodies anywhere.

Cursor reads none of these; it takes its guidance from AGENTS.md.

The catalog itself lives in the skills reference, generated from the same embedded bodies, so it is never a second description that can drift.

Install and update

magus agent is a pure data generator: it writes nothing unless you name a destination directory.

magus agent install .claude/skills          # write to a repo-relative dir; refuses to overwrite
magus agent install .claude/skills --force  # overwrite after a magus upgrade
magus agent install .claude/skills --prune  # also remove skills this binary no longer ships
magus agent install --tar                   # stream a tar of every skill to stdout
magus agent sample                          # print a whole starter AGENTS.md
magus doctor                                # are the installed skills current? (per location)
magus doctor --fix                          # reinstall whatever it reports stale

Commit what install writes, so every teammate's agent shares the same instructions.

--prune is not implied by --force, on purpose. --force overwrites files the command is about to write and can name; --prune deletes directories you have not seen, chosen by a rule inside a binary you may have just upgraded. Without it, install still reports what is stale. Only skills magus wrote are candidates - a hand-authored one beside them is never touched.

Write-mode destinations are relative to --dir (default .). Absolute paths and ~ prefixes are refused unless --global is set, to keep magus from silently writing outside the working tree. The supported route to an absolute destination is --tar, which lets your shell do the writes - so the guard hook, the sandbox, and your audit log all see the operation you typed:

magus agent install --tar | tar -xf - -C .claude/skills
magus agent install --tar | tar -xf - -C ~/.config/opencode/skills

A host discovers skills at session start, so restart the agent session after an install or a --force refresh. An already-open session keeps the skill set it launched with. The same launch-time rule applies to MCP tools; see MCP.

Two permutations, both installed

Every skill has two hand-authored permutations, and install writes both.

.claude/skills/magus-vcs-hygiene/SKILL.md        # the primary, short form
.claude/skills/magus-vcs-hygiene-full/SKILL.md   # its always-full twin

The short form is not the beginner form, and reading it that way gets the trade backwards. A capable model can work the mechanical steps out from -h and magus describe; what it cannot work out is which failures are silent, what is load-bearing, and where a judgment call is being asked of it. So the primary sheds ENUMERATION and keeps JUDGMENT.

The twin exists because a session that loads the short form can still delegate work to a reader that never made that bet. Point a sub-agent at the -full name and it gets the long form. The twin announces itself in the host's own skill listing, so a sub-agent browsing for a skill finds it without being told, and the primary spends no context pointing at it. Twins are loaded on demand rather than always, so they do not count against the context cost install reports.

Both are curated. The short form is not a summary and not model-generated. There is exactly one hand-written body per skill, and its author marks the spans only the full form keeps, so the two cannot come to describe different behavior: one source of truth to edit, one to review.

They also version together. The installed file's stamp names which form you have:

metadata:
  agent-skill-version: 37
  knowledge-schema-version: 9
  skill-content: 45653b90928c
  skill-variant: simple

skill-content is the digest of the source body, so it is identical for both forms. That is deliberate: a per-form digest would let one look current against a source its sibling had already outgrown.

AGENTS.md is yours

No command writes your AGENTS.md, and there will not be one. magus agent install prints the managed magus block - between its begin and end markers, on stderr - and you paste it in.

That is a deliberate limit, not a missing feature. magus agent install-agents-md used to manage the block in place: creating the file when absent, replacing the block on re-run, preserving your bytes outside the markers. It was the careful version of an installer appending to your .bashrc, and still the wrong shape. The file belongs to you, merge logic like that is never as careful as it looks, and a re-run leaves bytes you did not write and cannot easily audit.

The offer is scoped to when it is useful. Install reads your AGENTS.md, compares the block's stamp against the running binary, and:

So a --force reinstall does not dump 80 lines of Markdown at you every time. It is a hint, so MAGUS_HINTS_ENABLED=false silences it along with the others. magus agent sample prints the same block inside a whole starter file and is never gated.

There is no --tar for the block. Piping it into tar -xf - would overwrite that file with magus's idea of its contents, which is exactly what magus stopped doing.

Drift

Every installed file, and the AGENTS.md block, carries a generated stamp with the agent-skill version and the knowledge schema version. magus doctor compares those against the running binary for every well-known location it finds installed (.agents/skills, .claude/skills, .opencode/skills, and the AGENTS.md block), so a magus upgrade that changes the tool surface shows up as actionable drift rather than silently wrong instructions.

Do not hand-edit installed skills; change flows through re-running install. The AGENTS.md block is the exception in one direction only: you paste it, so refreshing it means replacing the block yourself, and everything outside the markers is yours.

Where guidance belongs

The skills teach the magus tool surface and nothing else. Keep each kind of guidance at the one layer that owns it, because agents pay for every duplicated line in every session.

• Your agent harness already covers generic behavior - when to ask, how to report. Do not restate it anywhere.
• Your repository's own instruction file (CLAUDE.md, AGENTS.md) carries repo conventions and team working style.
• The installed skills carry the magus HOW; the committed MAGUS.md carries the workspace WHAT. Both are generated - edit neither by hand.
• A rule that is about magus but true only HERE ("this target is slow, narrow it", "that directory is generated by a tool magus does not run") has no layer above it. It does not belong upstream, and burying it in your instruction file costs every session.

Put that last kind in a local skill next to the installed ones, under a name magus does not ship - magus-local-development by convention. magus agent install writes only the names it ships and magus doctor grades only those, so a local skill is neither overwritten nor reported as drift, and no configuration is needed to make a host find it. The magus-workspace-rules skill carries the stamp format and the rest of the method. When a local rule turns out to be true everywhere, it graduates upstream as a pull request against internal/agent/skills/, or as an issue quoting the stamped rule.