[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M76WVB4K1286WMJ7C3SHAFK2":3,"skill-same:01M76WVB4K1286WMJ7C3SHAFK2":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M76WVB4K1286WMJ7C3SHAFK2","magus-skill-authoring",null,"The working method for building and maintaining what magus installs for agents in THIS repo: the embedded skills, MCP tools, hints, and MAGUS.md routing. Use when editing anything under internal\u002Fagent\u002Fskills\u002F, the MCP registry, or agent install, or when evaluating what agents can learn from magus. Hand-authored and committed; NOT in the installed set, and never shipped in the binary.","egladman\u002Fmagus","egladman","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F8713153?v=4","01M75H42QB5A4X82APZF4H44GM","Eli Gladman","01M75H42R1K59Z7JWAP621J849",3,"GPL-3.0","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmagus-skill-authoring\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: magus-skill-authoring\ndescription: \"The working method for building and maintaining what magus installs for agents in THIS repo: the embedded skills, MCP tools, hints, and MAGUS.md routing. Use when editing anything under internal\u002Fagent\u002Fskills\u002F, the MCP registry, or agent install, or when evaluating what agents can learn from magus. Hand-authored and committed; NOT in the installed set, and never shipped in the binary.\"\n---\n\n# Authoring the skills, MCP tools and hints\n\nThis is the working method behind the magus skills, so any model, strong or weak,\nmaintains them the same way. The skills exist to stop agents guessing, so the\nprocess that writes them cannot guess either.\n\n## 1. Empiricism before documentation\n\nNever teach behavior you have not executed against a freshly built binary in this\nsession:\n\n1. Build HEAD (`magus run go-build .`).\n2. Start the server.\n3. Call the actual tool, over MCP HTTP and the CLI.\n4. Paste the observed output into your analysis before writing any skill text.\n\nPrecedent: the registry advertised dry_run as \"print what would run without\nexecuting\". The verified reality was zero bytes of output AND regenerated files on\ndisk. A skill written from the docs would have taught a \"safe preview\" that\nsilently mutates the tree.\n\n## 2. Hunt the silent failure\n\nEmpty output, zero matches, and exit 1 with no text are findings, not\ninconveniences. Probe every claim adversarially before teaching it.\n\nFix the tool before teaching the workaround. When `project:docs kind:function render`\nreturned 0, the wrong response was a workaround in the skill. The right one traced\nthe scorer, fixed the filter, and added a regression test.\n\nWhen the fix is out of reach, teach ONLY verified idioms. File the gap where a reader\nfinds it: the plans doc, a task, the harness memory.\n\n## 3. One source of truth, drift-gated\n\n- The installed skills are generated and embedded in the binary. Each copy\n  carries its skill's content digest, the stamp format and the schema version.\n  `magus doctor`'s agent-skills check grades them. A change to one skill\n  restamps only that skill's copies. Never hand-edit an installed copy; edit\n  internal\u002Fagent\u002Fskills\u002F and re-run `magus agent install \u003Cdest-dir> --force`\n  (here: .claude\u002Fskills).\n- Every destination receives identical bytes (a test asserts it). magus is\n  agent-host agnostic: no host name appears in code. Host-specific glue (hook\n  event shapes, config dialects) is documentation over neutral mechanisms:\n  explicit install destinations, the agent hook verdict, --from-json\n  extraction, -o template rendering. Never a per-host code path.\n- Skills teach the stable HOW; the workspace WHAT lives in MAGUS.md and the live\n  tools. A skill that mentions this repo's specifics is a bug.\n\n## 3b. Two forms from one body: mark the why, then shorten the rest\n\nA skill body is a `text\u002Ftemplate` rendered against the variant, so a form is an\nordinary `if` action. The whole vocabulary is three branching constructs plus the\nregistry lookups in section 3c:\n\n```markdown\nRun the target first{{if .Full}}, because a raw tool bypasses the cache{{end}}.\n\n{{if .Short}}Full explains this at length below.{{end}}\n\nRead `llms.txt` first{{if .Full}}, because guessing a URL wastes a fetch and the\nindex is authoritative{{else}}: it is the index{{end}}.\n```\n\nUnconditional text is in both forms.\n\n- No else arm means \"full says more here\".\n- An else arm means \"both forms say this, at different lengths\". It is the ONLY\n  construct that shortens something both must express.\n- A bare `.Short` arm means \"short says this and full says nothing\". That is\n  almost always a mistake worth catching in review.\n\nMeasured 2026-07-31: the ten shipped skills had 137 full-only branches and only 28\nelse arms. Most distinctions are still deletion, not rewording. Reach for an else\narm whenever a passage survives into short at full length.\n\nA third form costs a constant, not a new markup convention:\n\n```markdown\n{{if .Is \"minimal\"}}bare imperative{{else if .Full}}the long version{{else}}the short one{{end}}\n```\n\n### 3c. Never type a command path; resolve it\n\nA skill is read in someone else's repo, where nobody can check that a named command\nstill exists. A retyped path is the one error that reaches its reader intact and\nstays wrong. Resolve it instead:\n\n```markdown\nRun `{{cmd \"agent harness verify\"}}`, then read what it reports.\n```\n\n`cmd` looks the path up in `internal\u002Fhint`'s `AllCommands` and fails the INSTALL on\na miss, naming the path. A renamed verb either updates every skill that mentions it\nor stops the build. The failure lands on whoever moved the command, not on an agent\na month later.\n\nRegister the command in `internal\u002Fhint\u002Fcli_command.go` first; an unregistered path\nis a lookup failure, not a silent pass. It always renders the PATH spelling\n(`magus ...`), never this process's `.\u002Fmagus`: the reader's checkout is not ours.\n\nThe whole vocabulary, each resolving against the registry that defines it:\n\n| write | renders | resolves against |\n| --- | --- | --- |\n| `{{cmd \"agent harness verify\"}}` | `magus agent harness verify` | `hint.AllCommands` |\n| `{{tool \"client\"}}` | `client` | `hint.AllToolNames` (a `magus_` prefix is tried when the bare name misses) |\n| `{{skill \"vcs-hygiene\"}}` | `magus-vcs-hygiene` | the shipped catalog |\n| `{{buzz \"harness.provider\"}}` | `magus\\harness.provider` | the magus host module |\n| `{{mgs \"MGS2001\"}}` | `MGS2001` | the diagnostic registry |\n| `{{mgslink \"MGS2001\"}}` | a markdown link to its docs | the diagnostic registry |\n\nEach key is the SHORT form and each output the full one, so the call is never the\nanswer retyped. The two diagnostic functions split by job:\n\n- A code inside a graph node id, a URL pattern, or a quoted literal is DATA: use\n  `mgs`.\n- A code a sentence cites takes `mgslink`. The URL's category segment follows the\n  code's range, so no reader can derive it from the digits.\n\nThe `skill` lookup resolves only skills magus SHIPS. A local skill name\n(`magus-local-development`) stays literal on purpose: magus does not install it,\nso there is nothing to check it against.\n\nA new function in `skillFuncs` inherits the obligation `validateActionPipe`\ndocuments: it renders the same text in both forms. Otherwise the two forms stop\ndescribing one behavior and nothing catches it.\n\n### Showing template syntax inside a skill\n\nThe body IS a template, fenced code blocks included. A skill that documents template\nsyntax must escape it as a string constant. magus-run documents `-o template` and\nmagus-buzz-lang documents mustache; both hit this:\n\n```markdown\n`-o template='{{\"{{.Field}}\"}}'`\n```\n\nGetting it wrong fails loudly at install, never as a silently mangled file. An\nunknown function is a parse error; an unknown field is an execute error.\n\n### Who the short form is for, and therefore what it cuts\n\nShort is not the beginner form. It is installed for the most capable readers,\nwhich can re-derive an imperative from the MCP tool list. So **short sheds\nENUMERATION and keeps JUDGMENT.** It is not \"the steps without the why\". Dropping\nthe why hands the strongest reader the half it could reconstruct and takes away\nthe half it could not.\n\nAsk of every branch: could a capable reader work this out from `magus describe`,\n`-h`, or the docs? Then it is enumeration, and short can lose it. Could they only\nlearn it by making the mistake? Then it is judgment, and it stays.\n\nNot every instruction tolerates losing its rationale:\n\n- MECHANICAL instructions are enumerable and self-justifying. `run magus affected ci\n  before calling the work done` determines the action alone. Mark the why freely.\n- JUDGMENT instructions ask the reader to recognize an instance nobody enumerated.\n  `never a whole-tree git op to verify a build` is one: its why (a concurrent\n  agent's untracked work dies) lets a reader generalize. Keep a terse why in short\n  via an else arm instead of dropping it.\n\nThe sharpest test is silence. A failure that ANNOUNCES itself teaches the reader and\nneeds no rationale in short. A silent failure can only arrive as text, because\nnothing in the session ever says it. Examples: an edit that stops existing, a guard\nthat fails open, a pipe that turns a failing gate into exit 0.\n\nThe evidence: an ablation of repository context files (arXiv:2602.11988) found\nimperative instructions followed well, while background and overview prose is not\nworth its tokens. That licenses cutting BACKGROUND (what magus is, why it exists),\nnot the why of a judgment instruction.\n\n### Compress the short form to the floor; keep the full form for people\n\nThe short form is `agent-compact`: only an agent reads it, so write it grammar-free\nand compressed to the floor.\n\n- Drop articles, linking verbs, \"you\", filler and emphasis.\n- Keep every KEEP word: negation (not, never, no, without) and obligation (must,\n  only). Scope (every, all, any, each, except) is one too. So are condition (if,\n  unless, when, until) and order (before, after, then, first, last).\n- Keep every number with its unit, and every identifier, path and flag.\n- Write one fact per line, `key: value` lines over tables, and `->` for \"then\".\n- Spell negation as a word, never `!`.\n- Abbreviate only a word of 2 or more tokens: `k8s`, `w\u002F` and `e.g.` cost more than\n  the word.\n\nThis reverses the older \"terse, not de-grammared\" guidance. The 2026-10-13 eval ran\n`magus run agent-eval .` (Sonnet, 3 tasks x 3 runs):\n\n- c2, the short skills rewritten to the floor, used 14.9% fewer tokens than short.\n- c2 passed 9\u002F9 against full's 8\u002F9, with cache writes 7% lower.\n- n=9 can exclude a large pass drop, not a small one.\n\nThe full form stays grammatical prose: it is the copy for people and weaker models.\n\nproofread judges a body under internal\u002Fagent\u002Fskills\u002F as the `skill-template` kind in\nhack\u002Flint\u002Fmarkdown-proofread.buzz. The short form is `agent-compact`; text only the\nfull form shows is `reference`. The compact lint rules advise and never deny until\nthe short forms are compressed:\n\n- `compact-filler`: articles, linking verbs, filler, with the tokens saved;\n- `compact-markup`: bold, italic and tables;\n- `compact-costly-abbrev` and `compact-symbol-negation`;\n- `compact-line`: over 21 words joining clauses;\n- `compact-duplicate`: a line restating an earlier one.\n\nA hand-written skill or AGENTS.md is `agent-brief`: terse but grammatical. The terse\nlint rules refuse a sentence over 25 words, a paragraph over 60, and a wordy phrase\nsuch as `in order to`.\n\nBoth forms refuse a bare `rule`. In a skill, `rule` means only what magus enforces,\nso name the mechanism: a guard, workspace or lint rule, or its id in code. Write anything\nelse as an instruction. Name a guard rule rather than restate what it refuses; its\nfirst denial teaches the fix.\n\nIn the full form, write short declarative sentences and imperative steps. Prefer a\nlist when steps are a sequence. Never restate what a heading says. Move examples, history and the\nreasoning behind an instruction into a `.Full` arm when it stands without them.\n\nWhen you cut:\n\n- Never put the LOAD-BEARING instruction inside a `.Full` arm. That is the one\n  command or path short cannot act without, or the CORRECT half of a WRONG\u002FCORRECT\n  pair. Short must still do the thing.\n- An EXHAUSTIVE enumeration is exactly what short sheds: every flag of a command,\n  every kind in a table, every variant of a form. Put it in a `.Full` arm and have\n  short name where to get it (`-h`, `magus describe \u003Cthing>`, a docs URL). That is\n  progressive disclosure: a capable reader fetches an enumeration far more cheaply\n  than it recovers a judgment.\n- War stories, \"otherwise X\" clauses, and illustrative examples go in a `.Full`\n  arm. The why of a judgment instruction does NOT: shorten it into an else arm.\n- Cut on a clause boundary. `foo{{if .Full}}, because bar{{end}}.` reads as `foo.`\n  in short; a mid-clause cut can strip a KEEP word.\n- A malformed template is a parse or execute error at install, which also catches\n  typos the old scheme let through as literal text.\n- A passage that survives into short at full length is a candidate for an else\n  arm, not proof the ceiling is reached.\n- `TestEveryEmbeddedSkillHasBothForms` fails for any skill whose two forms are\n  byte-identical, so a skill with no marked rationale is caught. `--skill-form`\n  picks what an install writes: `both` (the default: the short body under each\n  skill's own name plus a `\u003Cname>-full` twin), `short`, or `full`.\n\n## 4. Breadcrumbs are load-bearing\n\nEvery named thing magus exposes has a stable, resolvable ID:\n\n- tool names (internal\u002Fhint ToolName constants);\n- CLI paths (internal\u002Fhint Command values);\n- output refs (out1a2b3c), diagnostics (MGSxxxx), graph node IDs (kind:name).\n\nProse that points at another of those things goes through one of those IDs. A rename then\nbreaks the build or a test, never an agent at 2am.\n\nHints stay terse and earned: one line, only on an error or on a result that mints\nsomething chainable. A weaker model follows breadcrumbs it could never have\nplanned; leave them.\n\n## 5. Write for the weakest reader\n\n- Frontmatter descriptions carry the triggers (\"Use when...\", \"Do NOT use\n  for...\").\n- Bodies use imperative fast paths, WRONG\u002FCORRECT pairs, and tables over prose.\n- Defer to `-h` and live tools for anything versionable.\n- Plain ASCII, no emojis (tests enforce it).\n- Spell every instruction out: one the reader must infer is inferred differently\n  by every model.\n\n## 5b. Phrase verification as proof, not as care\n\nAn instruction phrased as care is satisfiable by prose: an agent asserts it was\ncareful and the sentence is met. Phrased as a proof obligation, it can only be met\nby evidence, because it names the artifact that settles it. When the evidence is\ncheap, write the obligation.\n\nWorked example, from magus-vcs-hygiene:\n\n```markdown\nWRONG: Distinguish real drift from environmental noise before you act.\nCORRECT: Prove drift by regenerating a SECOND time, never by reading the diff\nand judging it.\n```\n\nBoth point at the same procedure. Only the second fails visibly when nobody runs\nit: a second regeneration is in the transcript or it is not. Apply it to:\n\n- gates: \"show a gate you added FAILING before you trust its green\";\n- collision claims: \"the check REPORTS the write sets disjoint\", not \"the leases\n  are genuinely independent\";\n- reported findings: \"carries the command that reproduces it\".\n\nThe limit is cost. A judgment instruction with no cheap proof keeps its judgment framing.\n`never a whole-tree git op to verify a build` has nothing to run; a fake obligation\nwould trade an instruction the reader can generalize for a ritual.\n\n## 6. Record the why, then verify the whole\n\n- Decisions with a why go to the harness memory, so the next session, possibly a\n  lesser model, inherits them. Read them before re-litigating anything.\n- After editing skills, in this order:\n  1. `magus run go-build .`: the bodies are go:embed'd, so nothing below reads\n     your edit until the binary carries it.\n  2. `magus run go::go-test . --silent -- -run 'TestAgent|TestSkill' .\u002Fcmd\u002Fmagus\u002F`\n     (frontmatter, ASCII, byte-identity, install\u002Fverify testscripts). The raw\n     `go test .\u002Fcmd\u002Fmagus\u002F` is guard-denied. magus flags go BEFORE the `--`;\n     everything after it forwards to the test binary.\n  3. `.\u002Fmagus agent install .claude\u002Fskills --force`: reinstall the dogfooded\n     copies, which are stamped and otherwise read as drift.\n  4. Refresh the AGENTS.md managed block. `.\u002Fmagus agent starter` prints the\n     current block (so does `agent install`). Replace everything between the\n     `magus:skills:begin` and `magus:skills:end` markers with it and leave the rest\n     alone. magus never writes AGENTS.md; `magus doctor`'s agent-skills advice\n     names the stale block.\n  5. `.\u002Fmagus doctor` says up to date. `magus doctor --fix` runs the remedy each\n     finding names, where one exists.\n  6. `magus affected ci --no-default-charms` before calling the work done.\n","# Authoring the skills, MCP tools and hints\n\nThis is the working method behind the magus skills, so any model, strong or weak,\nmaintains them the same way. The skills exist to stop agents guessing, so the\nprocess that writes them cannot guess either.\n\n## 1. Empiricism before documentation\n\nNever teach behavior you have not executed against a freshly built binary in this\nsession:\n\n1. Build HEAD (`magus run go-build .`).\n2. Start the server.\n3. Call the actual tool, over MCP HTTP and the CLI.\n4. Paste the observed output into your analysis before writing any skill text.\n\nPrecedent: the registry advertised dry_run as \"print what would run without\nexecuting\". The verified reality was zero bytes of output AND regenerated files on\ndisk. A skill written from the docs would have taught a \"safe preview\" that\nsilently mutates the tree.\n\n## 2. Hunt the silent failure\n\nEmpty output, zero matches, and exit 1 with no text are findings, not\ninconveniences. Probe every claim adversarially before teaching it.\n\nFix the tool before teaching the workaround. When `project:docs kind:function render`\nreturned 0, the wrong response was a workaround in the skill. The right one traced\nthe scorer, fixed the filter, and added a regression test.\n\nWhen the fix is out of reach, teach ONLY verified idioms. File the gap where a reader\nfinds it: the plans doc, a task, the harness memory.\n\n## 3. One source of truth, drift-gated\n\n- The installed skills are generated and embedded in the binary. Each copy\n  carries its skill's content digest, the stamp format and the schema version.\n  `magus doctor`'s agent-skills check grades them. A change to one skill\n  restamps only that skill's copies. Never hand-edit an installed copy; edit\n  internal\u002Fagent\u002Fskills\u002F and re-run `magus agent install \u003Cdest-dir> --force`\n  (here: .claude\u002Fskills).\n- Every destination receives identical bytes (a test asserts it). magus is\n  agent-host agnostic: no host name appears in code. Host-specific glue (hook\n  event shapes, config dialects) is documentation over neutral mechanisms:\n  explicit install destinations, the agent hook verdict, --from-json\n  extraction, -o template rendering. Never a per-host code path.\n- Skills teach the stable HOW; the workspace WHAT lives in MAGUS.md and the live\n  tools. A skill that mentions this repo's specifics is a bug.\n\n## 3b. Two forms from one body: mark the why, then shorten the rest\n\nA skill body is a `text\u002Ftemplate` rendered against the variant, so a form is an\nordinary `if` action. The whole vocabulary is three branching constructs plus the\nregistry lookups in section 3c:\n\n```markdown\nRun the target first{{if .Full}}, because a raw tool bypasses the cache{{end}}.\n\n{{if .Short}}Full explains this at length below.{{end}}\n\nRead `llms.txt` first{{if .Full}}, because guessing a URL wastes a fetch and the\nindex is authoritative{{else}}: it is the index{{end}}.\n```\n\nUnconditional text is in both forms.\n\n- No else arm means \"full says more here\".\n- An else arm means \"both forms say this, at different lengths\". It is the ONLY\n  construct that shortens something both must express.\n- A bare `.Short` arm means \"short says this and full says nothing\". That is\n  almost always a mistake worth catching in review.\n\nMeasured 2026-07-31: the ten shipped skills had 137 full-only branches and only 28\nelse arms. Most distinctions are still deletion, not rewording. Reach for an else\narm whenever a passage survives into short at full length.\n\nA third form costs a constant, not a new markup convention:\n\n```markdown\n{{if .Is \"minimal\"}}bare imperative{{else if .Full}}the long version{{else}}the short one{{end}}\n```\n\n### 3c. Never type a command path; resolve it\n\nA skill is read in someone else's repo, where nobody can check that a named command\nstill exists. A retyped path is the one error that reaches its reader intact and\nstays wrong. Resolve it instead:\n\n```markdown\nRun `{{cmd \"agent harness verify\"}}`, then read what it reports.\n```\n\n`cmd` looks the path up in `internal\u002Fhint`'s `AllCommands` and fails the INSTALL on\na miss, naming the path. A renamed verb either updates every skill that mentions it\nor stops the build. The failure lands on whoever moved the command, not on an agent\na month later.\n\nRegister the command in `internal\u002Fhint\u002Fcli_command.go` first; an unregistered path\nis a lookup failure, not a silent pass. It always renders the PATH spelling\n(`magus ...`), never this process's `.\u002Fmagus`: the reader's checkout is not ours.\n\nThe whole vocabulary, each resolving against the registry that defines it:\n\n| write | renders | resolves against |\n| --- | --- | --- |\n| `{{cmd \"agent harness verify\"}}` | `magus agent harness verify` | `hint.AllCommands` |\n| `{{tool \"client\"}}` | `client` | `hint.AllToolNames` (a `magus_` prefix is tried when the bare name misses) |\n| `{{skill \"vcs-hygiene\"}}` | `magus-vcs-hygiene` | the shipped catalog |\n| `{{buzz \"harness.provider\"}}` | `magus\\harness.provider` | the magus host module |\n| `{{mgs \"MGS2001\"}}` | `MGS2001` | the diagnostic registry |\n| `{{mgslink \"MGS2001\"}}` | a markdown link to its docs | the diagnostic registry |\n\nEach key is the SHORT form and each output the full one, so the call is never the\nanswer retyped. The two diagnostic functions split by job:\n\n- A code inside a graph node id, a URL pattern, or a quoted literal is DATA: use\n  `mgs`.\n- A code a sentence cites takes `mgslink`. The URL's category segment follows the\n  code's range, so no reader can derive it from the digits.\n\nThe `skill` lookup resolves only skills magus SHIPS. A local skill name\n(`magus-local-development`) stays literal on purpose: magus does not install it,\nso there is nothing to check it against.\n\nA new function in `skillFuncs` inherits the obligation `validateActionPipe`\ndocuments: it renders the same text in both forms. Otherwise the two forms stop\ndescribing one behavior and nothing catches it.\n\n### Showing template syntax inside a skill\n\nThe body IS a template, fenced code blocks included. A skill that documents template\nsyntax must escape it as a string constant. magus-run documents `-o template` and\nmagus-buzz-lang documents mustache; both hit this:\n\n```markdown\n`-o template='{{\"{{.Field}}\"}}'`\n```\n\nGetting it wrong fails loudly at install, never as a silently mangled file. An\nunknown function is a parse error; an unknown field is an execute error.\n\n### Who the short form is for, and therefore what it cuts\n\nShort is not the beginner form. It is installed for the most capable readers,\nwhich can re-derive an imperative from the MCP tool list. So **short sheds\nENUMERATION and keeps JUDGMENT.** It is not \"the steps without the why\". Dropping\nthe why hands the strongest reader the half it could reconstruct and takes away\nthe half it could not.\n\nAsk of every branch: could a capable reader work this out from `magus describe`,\n`-h`, or the docs? Then it is enumeration, and short can lose it. Could they only\nlearn it by making the mistake? Then it is judgment, and it stays.\n\nNot every instruction tolerates losing its rationale:\n\n- MECHANICAL instructions are enumerable and self-justifying. `run magus affected ci\n  before calling the work done` determines the action alone. Mark the why freely.\n- JUDGMENT instructions ask the reader to recognize an instance nobody enumerated.\n  `never a whole-tree git op to verify a build` is one: its why (a concurrent\n  agent's untracked work dies) lets a reader generalize. Keep a terse why in short\n  via an else arm instead of dropping it.\n\nThe sharpest test is silence. A failure that ANNOUNCES itself teaches the reader and\nneeds no rationale in short. A silent failure can only arrive as text, because\nnothing in the session ever says it. Examples: an edit that stops existing, a guard\nthat fails open, a pipe that turns a failing gate into exit 0.\n\nThe evidence: an ablation of repository context files (arXiv:2602.11988) found\nimperative instructions followed well, while background and overview prose is not\nworth its tokens. That licenses cutting BACKGROUND (what magus is, why it exists),\nnot the why of a judgment instruction.\n\n### Compress the short form to the floor; keep the full form for people\n\nThe short form is `agent-compact`: only an agent reads it, so write it grammar-free\nand compressed to the floor.\n\n- Drop articles, linking verbs, \"you\", filler and emphasis.\n- Keep every KEEP word: negation (not, never, no, without) and obligation (must,\n  only). Scope (every, all, any, each, except) is one too. So are condition (if,\n  unless, when, until) and order (before, after, then, first, last).\n- Keep every number with its unit, and every identifier, path and flag.\n- Write one fact per line, `key: value` lines over tables, and `->` for \"then\".\n- Spell negation as a word, never `!`.\n- Abbreviate only a word of 2 or more tokens: `k8s`, `w\u002F` and `e.g.` cost more than\n  the word.\n\nThis reverses the older \"terse, not de-grammared\" guidance. The 2026-10-13 eval ran\n`magus run agent-eval .` (Sonnet, 3 tasks x 3 runs):\n\n- c2, the short skills rewritten to the floor, used 14.9% fewer tokens than short.\n- c2 passed 9\u002F9 against full's 8\u002F9, with cache writes 7% lower.\n- n=9 can exclude a large pass drop, not a small one.\n\nThe full form stays grammatical prose: it is the copy for people and weaker models.\n\nproofread judges a body under internal\u002Fagent\u002Fskills\u002F as the `skill-template` kind in\nhack\u002Flint\u002Fmarkdown-proofread.buzz. The short form is `agent-compact`; text only the\nfull form shows is `reference`. The compact lint rules advise and never deny until\nthe short forms are compressed:\n\n- `compact-filler`: articles, linking verbs, filler, with the tokens saved;\n- `compact-markup`: bold, italic and tables;\n- `compact-costly-abbrev` and `compact-symbol-negation`;\n- `compact-line`: over 21 words joining clauses;\n- `compact-duplicate`: a line restating an earlier one.\n\nA hand-written skill or AGENTS.md is `agent-brief`: terse but grammatical. The terse\nlint rules refuse a sentence over 25 words, a paragraph over 60, and a wordy phrase\nsuch as `in order to`.\n\nBoth forms refuse a bare `rule`. In a skill, `rule` means only what magus enforces,\nso name the mechanism: a guard, workspace or lint rule, or its id in code. Write anything\nelse as an instruction. Name a guard rule rather than restate what it refuses; its\nfirst denial teaches the fix.\n\nIn the full form, write short declarative sentences and imperative steps. Prefer a\nlist when steps are a sequence. Never restate what a heading says. Move examples, history and the\nreasoning behind an instruction into a `.Full` arm when it stands without them.\n\nWhen you cut:\n\n- Never put the LOAD-BEARING instruction inside a `.Full` arm. That is the one\n  command or path short cannot act without, or the CORRECT half of a WRONG\u002FCORRECT\n  pair. Short must still do the thing.\n- An EXHAUSTIVE enumeration is exactly what short sheds: every flag of a command,\n  every kind in a table, every variant of a form. Put it in a `.Full` arm and have\n  short name where to get it (`-h`, `magus describe \u003Cthing>`, a docs URL). That is\n  progressive disclosure: a capable reader fetches an enumeration far more cheaply\n  than it recovers a judgment.\n- War stories, \"otherwise X\" clauses, and illustrative examples go in a `.Full`\n  arm. The why of a judgment instruction does NOT: shorten it into an else arm.\n- Cut on a clause boundary. `foo{{if .Full}}, because bar{{end}}.` reads as `foo.`\n  in short; a mid-clause cut can strip a KEEP word.\n- A malformed template is a parse or execute error at install, which also catches\n  typos the old scheme let through as literal text.\n- A passage that survives into short at full length is a candidate for an else\n  arm, not proof the ceiling is reached.\n- `TestEveryEmbeddedSkillHasBothForms` fails for any skill whose two forms are\n  byte-identical, so a skill with no marked rationale is caught. `--skill-form`\n  picks what an install writes: `both` (the default: the short body under each\n  skill's own name plus a `\u003Cname>-full` twin), `short`, or `full`.\n\n## 4. Breadcrumbs are load-bearing\n\nEvery named thing magus exposes has a stable, resolvable ID:\n\n- tool names (internal\u002Fhint ToolName constants);\n- CLI paths (internal\u002Fhint Command values);\n- output refs (out1a2b3c), diagnostics (MGSxxxx), graph node IDs (kind:name).\n\nProse that points at another of those things goes through one of those IDs. A rename then\nbreaks the build or a test, never an agent at 2am.\n\nHints stay terse and earned: one line, only on an error or on a result that mints\nsomething chainable. A weaker model follows breadcrumbs it could never have\nplanned; leave them.\n\n## 5. Write for the weakest reader\n\n- Frontmatter descriptions carry the triggers (\"Use when...\", \"Do NOT use\n  for...\").\n- Bodies use imperative fast paths, WRONG\u002FCORRECT pairs, and tables over prose.\n- Defer to `-h` and live tools for anything versionable.\n- Plain ASCII, no emojis (tests enforce it).\n- Spell every instruction out: one the reader must infer is inferred differently\n  by every model.\n\n## 5b. Phrase verification as proof, not as care\n\nAn instruction phrased as care is satisfiable by prose: an agent asserts it was\ncareful and the sentence is met. Phrased as a proof obligation, it can only be met\nby evidence, because it names the artifact that settles it. When the evidence is\ncheap, write the obligation.\n\nWorked example, from magus-vcs-hygiene:\n\n```markdown\nWRONG: Distinguish real drift from environmental noise before you act.\nCORRECT: Prove drift by regenerating a SECOND time, never by reading the diff\nand judging it.\n```\n\nBoth point at the same procedure. Only the second fails visibly when nobody runs\nit: a second regeneration is in the transcript or it is not. Apply it to:\n\n- gates: \"show a gate you added FAILING before you trust its green\";\n- collision claims: \"the check REPORTS the write sets disjoint\", not \"the leases\n  are genuinely independent\";\n- reported findings: \"carries the command that reproduces it\".\n\nThe limit is cost. A judgment instruction with no cheap proof keeps its judgment framing.\n`never a whole-tree git op to verify a build` has nothing to run; a fake obligation\nwould trade an instruction the reader can generalize for a ritual.\n\n## 6. Record the why, then verify the whole\n\n- Decisions with a why go to the harness memory, so the next session, possibly a\n  lesser model, inherits them. Read them before re-litigating anything.\n- After editing skills, in this order:\n  1. `magus run go-build .`: the bodies are go:embed'd, so nothing below reads\n     your edit until the binary carries it.\n  2. `magus run go::go-test . --silent -- -run 'TestAgent|TestSkill' .\u002Fcmd\u002Fmagus\u002F`\n     (frontmatter, ASCII, byte-identity, install\u002Fverify testscripts). The raw\n     `go test .\u002Fcmd\u002Fmagus\u002F` is guard-denied. magus flags go BEFORE the `--`;\n     everything after it forwards to the test binary.\n  3. `.\u002Fmagus agent install .claude\u002Fskills --force`: reinstall the dogfooded\n     copies, which are stamped and otherwise read as drift.\n  4. Refresh the AGENTS.md managed block. `.\u002Fmagus agent starter` prints the\n     current block (so does `agent install`). Replace everything between the\n     `magus:skills:begin` and `magus:skills:end` markers with it and leave the rest\n     alone. magus never writes AGENTS.md; `magus doctor`'s agent-skills advice\n     names the stale block.\n  5. `.\u002Fmagus doctor` says up to date. `magus doctor --fix` runs the remedy each\n     finding names, where one exists.\n  6. `magus affected ci --no-default-charms` before calling the work done.\n",{"name":5,"description":7},"main","5f0df014d9eaf4aea1a930b0bd13c3338e2642de",".agents\u002Fskills\u002Fmagus-skill-authoring",0,"https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus","http:\u002F\u002Feli.gladman.cc\u002Fmagus\u002F","https:\u002F\u002Fgithub.com\u002Fegladman","eli.gladman.cc","2026-11-14 12:23:44",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add egladman\u002Fmagus --skill magus-skill-authoring",{"tool":39,"command":40},"bunx","bunx skills add egladman\u002Fmagus --skill magus-skill-authoring",{"tool":42,"command":43},"pnpm","pnpm dlx skills add egladman\u002Fmagus --skill magus-skill-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmagus-skill-authoring\u002FSKILL.md",true,[],[48,54,60,66,72,78],{"skillNo":49,"name":50,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M76WWZ75J70NCG0TR23XDDE6","magus-workspace-rules","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-workspace-rules\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M76WWX72SY78KG03AVYFE768","magus-vcs-hygiene","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-vcs-hygiene\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M76WWTJYGRCKKXH948KN6RR3","magus-upstream-source","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-upstream-source\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M76WWRTBBAPNKM0PA2NG5Q3N","magus-upstream-docs","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-upstream-docs\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M76WWNTF03H9S5CN22QBX5ZK","magus-test-design","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-test-design\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M76WWJX1FPSWYD1RB8JXNF3C","magus-sdk","https:\u002F\u002Fgithub.com\u002Fegladman\u002Fmagus\u002Fblob\u002Fmain\u002Finternal\u002Fagent\u002Fskills\u002Fmagus-sdk\u002FSKILL.md",[],[]]