Mapwrite

An agent skill for Codex and Claude Code: agent-maintained project context, wiki protocols, layered code indexes, and low-token file discovery.

This skill helps coding agents answer three questions before they start editing:

1. What project knowledge should I read?
2. Which part of the codebase am I actually touching?
3. What should I update after I change it?

It is designed for repositories that want agents to maintain useful Markdown context without spending a huge amount of context reading unrelated specs, plans, logs, or code maps.

Why This Exists

Many agent-friendly repos eventually grow a project wiki: specs, plans, runbooks, decisions, and change logs. That helps, but a single wiki index often becomes overloaded with code inventory too.

This skill separates the two concerns:

• wiki/index.md indexes project knowledge: specs, plans, shards, runbooks.
• wiki/code-index/ indexes the codebase: subsystems, entrypoints, facades, boundaries, tests.

Agents use one navigation workflow, but the artifacts stay clean and small.

What Agents Learn

The skill teaches coding agents to:

• read root agent instructions first, such as AGENTS.md or CLAUDE.md
• read wiki/index.md as the wiki map
• read wiki/code-index/index.md only when touching code
• follow only the narrow code-index shard relevant to the task
• keep behavior specs under wiki/spec/
• keep implementation plans under wiki/plan/
• treat generated indexes as optional helpers, not source of truth
• update the right wiki/code-index/log files after changes

Installation

Install for Codex:

Copy-Item -Recurse .\skill\mapwrite $env:USERPROFILE\.codex\skills\

cp -R skill/mapwrite ~/.codex/skills/

Install for Claude Code:

Copy-Item -Recurse .\skill\mapwrite $env:USERPROFILE\.claude\skills\

cp -R skill/mapwrite ~/.claude/skills/

Restart the agent or start a new session so the skill metadata is loaded.

Claude Code can invoke it directly as:

/mapwrite

Codex can invoke it directly as:

Use $mapwrite

Usage

You can invoke it explicitly in Codex:

Use $mapwrite to add a repo wiki and code-index protocol.

Or in Claude Code:

/mapwrite add a repo wiki and code-index protocol

It should also trigger naturally for tasks like:

• "Create a wiki protocol for this repo."
• "Split the codebase index into nested agent-readable maps."
• "Update AGENTS.md so agents know what context to read."
• "Before editing this feature, find the right spec and code index shard."
• "Make my agents spend fewer tokens finding the right files."

Recommended Repository Layout

AGENTS.md
CLAUDE.md
wiki/
  index.md
  log.md
  spec/
  plan/
  code-index/
    index.md
    backend.md
    frontend.md
    tests.md

For larger repos, add one more level:

wiki/code-index/
  index.md
  backend.md
  backend/
    api.md
    services.md
    workers.md
    db.md

See examples/repo-layout.md for a fuller template.

Relationship To Generated Indexes

Generated symbol indexes and call graphs can be helpful, but they should live outside the human wiki, for example:

.agent-index/

This skill recommends excluding generated indexes from normal source-control churn unless your team explicitly wants them committed. Human-readable code maps should stay concise and navigational.

Compatibility

Mapwrite uses the SKILL.md convention shared by Codex skills and Claude Code skills. Claude Code loads personal skills from ~/.claude/skills/<skill-name>/SKILL.md; Codex loads skills from ~/.codex/skills/<skill-name>/SKILL.md.

Inspiration And Attribution

This project is inspired by two excellent ideas:

• Andrej Karpathy's llm-wiki pattern: agent-maintained Markdown knowledge that becomes a project memory.
• Eric Buess's claude-code-project-index: generated project indexes that give Claude Code architectural awareness.

This repo is not a fork of either project. It packages a complementary Codex skill focused on the navigation protocol between wiki knowledge and layered code maps.

License

MIT. See LICENSE.