Mischief Managed

A portable Agent Skill that saves a lean, searchable session note at the end of a coding-agent session: the decisions you made, the code you changed, what you validated, open risks, and follow-ups.

"Mischief managed." Close out a session and leave a trail you (or your next session) can pick up later.

It works across coding agents and lets you keep your notes in whatever knowledge base you already use.

Supported agents

The same SKILL.md is installed into each agent's skills directory:

Agent	Install location
Claude	~/.claude/skills/mischief-managed/
Cursor	~/.cursor/skills/mischief-managed/
Codex	~/.codex/skills/mischief-managed/
Pi	~/.pi/agent/skills/mischief-managed/
opencode	~/.config/opencode/skills/mischief-managed/

Supported knowledge bases

You pick where the notes go; the installer templates the skill accordingly:

• Obsidian - writes Markdown notes into a vault under Agent-Sessions/<Agent>/.
• Notion - creates a page under a parent page/database using whatever Notion tooling you have available (e.g. a Notion MCP server), with a Markdown fallback when none is present.
• Other - any folder-based KB (Logseq, plain Markdown, etc.); writes Markdown notes to a path you choose.

The Marauder's Map

Whatever knowledge base you pick, the skill also maintains a single index note - Marauders-Map.md at the root of your Agent-Sessions/ area (a page titled "The Marauder's Map" for Notion). Like the real thing, it reveals every footstep: a link to each session, grouped by agent, newest first, wrapped in the incantations.

It is kept current two ways:

• On save - each time the skill writes a session note, it adds that note's footstep to the map.
• On request - ask your agent to "redraw the Marauder's Map" and it rescans every session note and rebuilds the whole map.

And yes - the installer reveals itself with I solemnly swear that I am up to no good..., a trail of footprints, and signs off with Mischief managed. The animation is purely cosmetic; see Animations to turn it off.

Install

Interactive (pick agents + knowledge base):

curl -fsSL https://raw.githubusercontent.com/ethanolivertroy/mischief-managed/main/install.sh | sh

Or clone and run:

git clone https://github.com/ethanolivertroy/mischief-managed.git
cd mischief-managed
./install.sh

Non-interactive examples:

# Obsidian, all agents
./install.sh --agents all --kb obsidian --vault ~/Obsidian -y

# Notion, Claude + Cursor only
./install.sh --agents claude,cursor --kb notion --notion-target "Agent Sessions" -y

# Any other Markdown KB
./install.sh --agents pi --kb other --kb-name Logseq --kb-path ~/Logseq -y

Options

--agents LIST     Comma-separated agents or "all" (claude,cursor,codex,pi,opencode)
--kb NAME         Knowledge base: obsidian | notion | other
--kb-name NAME    Display name for the KB (used in the skill text)
--vault PATH      Obsidian vault path (kb=obsidian)
--kb-path PATH    Notes directory (kb=other)
--notion-target X Notion parent page/database name (kb=notion)
--fallback-path P Markdown fallback dir when no Notion tool is available (kb=notion)
-y, --yes         Non-interactive; accept defaults
--list            Show install status for each agent and exit
--uninstall       Remove the skill from selected agents
--dry-run         Show what would happen without writing
--no-animation    Disable the Marauder's Map terminal animation
-h, --help        Show this help

The installer backs up any existing SKILL.md to SKILL.md.bak before overwriting.

Animations

The installer plays a short Marauder's Map animation. It auto-disables when output is not an interactive terminal (e.g. piped into a file or CI), and you can force it off:

./install.sh --no-animation        # flag
MISCHIEF_NO_ANIM=1 ./install.sh    # env var
NO_COLOR=1 ./install.sh            # honors the NO_COLOR convention

It also falls back to plain ASCII when your locale is not UTF-8, and always restores the cursor if interrupted.

Status / uninstall

./install.sh --list
./install.sh --uninstall --agents all

How it works

install.sh assembles the final SKILL.md from three templates and substitutes your knowledge-base choice:

• templates/skill.head.md - intro and the runtime agent-detection logic (KB-agnostic).
• templates/kb/{obsidian,notion,generic}.md - where and how to write the note.
• templates/skill.tail.md - metadata command, note shape, content rules, and Marauder's Map upkeep.

The agent is detected at runtime from the active session (not from where the file is installed), so notes are always filed under the correct agent folder.

When run via curl | sh, the script downloads the templates it needs from this repo; when run from a clone, it uses the local templates/.

The repo-root SKILL.md (used for manual installs) is generated from the templates. If you edit the templates, regenerate it:

scripts/build-skill.sh          # rewrite SKILL.md
scripts/build-skill.sh --check  # CI uses this to fail on drift

Manual install

If you'd rather not run the script, the repo ships a ready-to-use SKILL.md (the Obsidian default). Copy it into any agent directory from the table above, in a folder named mischief-managed:

# example: Claude
mkdir -p ~/.claude/skills/mischief-managed
curl -fsSL https://raw.githubusercontent.com/ethanolivertroy/mischief-managed/main/SKILL.md \
  -o ~/.claude/skills/mischief-managed/SKILL.md

To target a different knowledge base, edit the Obsidian Vault Location and The Marauder's Map sections - or copy the matching snippet from templates/kb/ (notion.md or generic.md) over those sections. The bundled SKILL.md is just templates/skill.head.md + templates/kb/obsidian.md + templates/skill.tail.md spliced together, which is exactly what install.sh does for you.

License

MIT - see LICENSE.