Working in this repo

This is the mana skills repo. It is both a Claude Code plugin (mana, marketplace frankieramirez) and a skills.sh source. One layout serves both: skills/<name>/SKILL.md plus agents/.

Conventions

• Every SKILL.md has frontmatter with name equal to its directory name and a description that says when to use it, including the trigger phrases a user would type.
• A skill is named for the spell it casts (scan, remedy, dispel, mimic, banish, scry, cast, sift, mend, reveal, augur, conjure, attune, ward, ultima, portal, leyline). The one exception is setup-mana, named for what a new user would type. The name is flavour and only has to be typed. The description is what the model matches on, so it stays plain English, names the job, and lists the words a user would actually say. Never put the theme in a description, because nobody asks to have their prose dispelled.
• Ship files (capture.md, body.md, attach.md, open-pr.sh, text-frame.sh) live under skills/reveal/ and are copied to skills/cast/. Edit the reveal copies; scripts/validate.sh checks they match.
• Ticket files (agent-brief.md, tickets.sh) live under skills/sift/ and are copied to skills/conjure/, skills/cast/, skills/scry/, skills/ultima/, and (tickets.sh only) skills/setup-mana/, skills/scan/, skills/attune/, skills/portal/, and skills/vision/. skills/conjure/references/build-progress.md is copied to skills/cast/ and skills/scry/; edit the conjure copy. skills/scry/scripts/map.sh is copied to skills/portal/ and skills/vision/; edit the scry copy. Edit the sift copies; the same script checks they match. setup-mana owns references/triage-labels.md, which attune copies under the same rule. skills/augur/references/proof.md and skills/augur/scripts/prove.sh are copied to skills/scan/; edit the augur copies. skills/leyline/references/control-evidence.md and skills/leyline/scripts/conform.sh are copied to skills/sift/, skills/cast/, and skills/scan/; edit the leyline copies. Every label, issue, edge, claim, and next lookup on the tracker goes through tickets.sh, never a hand-written gh issue call.
• The tracker is whatever docs/agents/issue-tracker.md in the user's repo says: GitHub, Linear, Jira, local files, or prose the user wrote. setup-mana writes that file from the templates under skills/setup-mana/references/. A skill that touches tickets reads the file first and passes its Adapter flags: to tickets.sh.
• Prose follows the dispel skill: no em or en dashes, no "not X but Y", no rule of three, lead with the point. scripts/validate.sh fails on dashes.
• The prose rules stop at evals/. Eval prompts are written as slop on purpose, because that is the input a skill has to clean up, so the dash check in scripts/validate.sh scans skills, agents, output-styles, README.md, and CLAUDE.md and leaves evals/ alone. Widening that grep breaks the suite.
• A skill's supporting files live in references/ and are loaded by stage, not all at once. Name the stage that loads each one inside SKILL.md.
• Scripts under skills/*/scripts/ are bash. The GitHub paths depend only on git and gh. The Linear and Jira paths inside tickets.sh use python3 with the standard library and nothing else. No jq binary, no node, no pip packages.
• A SKILL.md shows a bundled script with its path written into the command, as bash "<SKILL_DIR>/scripts/x.sh". Never SKILL_DIR="..." on a line above it. A worktree-isolated or sandboxed session refuses an interpreter whose script path it cannot read off the command line, so the variable form costs the run several turns before the model falls back. Variables in other arguments are fine.
• The Archmage voice lives in skills/attune/references/archmage.md, with archmage-session.md and persona-activation.md beside it. scripts/sync-persona.sh copies the voice into every skill, rewrites each activation block, and generates output-styles/archmage.md for Claude Code. Edit the attune sources and run that script.
• Everything under agents/ is generated. Edit the reference file named in the manifest in scripts/shared-assets.json (skills/banish/references/comment-reaper.md, skills/mimic/references/ghost.md, skills/mend/references/weaver.md) and run scripts/sync-assets.sh. Adding an agent means a new manifest entry plus a line in plugin.json.
• Every behavior change bumps version in .claude-plugin/plugin.json and gets a line in CHANGELOG.md. Claude Code caches plugins by version, so a change without a bump does not reach installed copies.
• Nothing here references another plugin, marketplace, or skill by name. Skills must work standalone under Codex, Cursor, or Copilot where only the SKILL.md and its folder are installed. The one exception is portal, whose job is to name the skill it hands off to; it reads a sibling's SKILL.md when the folder is present and falls back to a plain prompt when it is not.

Checks

• scripts/validate.sh before every commit. CI runs the same script.
• scripts/similarity.py when touching scan or remedy: those started as forks and the rewrite is only done while every ratio stays under 0.30.

Local development

scripts/link-local.sh symlinks this checkout into ~/.claude/skills and ~/.claude/agents. Uninstall the mana plugin first (claude plugin uninstall mana@frankieramirez) or every skill appears twice.

Agent skills

Issue tracker: GitHub frankieramirez/mana. See docs/agents/issue-tracker.md. Triage labels: defaults. See docs/agents/triage-labels.md. Validation: scripts/validate.sh Proof: command output as an image Domain docs: single-context: CONTEXT.md and docs/adr/

Shared-asset ownership lives in scripts/shared-assets.json. Run scripts/sync-assets.sh after canonical edits; its --check mode is read-only. The agent and persona sync commands are scoped wrappers.