# atlas

atlas is a Claude Code skill that keeps project decisions and work records across sessions. It activates when agents need past rulings, a handoff, or a plan for queued work.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 135 repo stars
- Author: Brandon White
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/bloodfeast/atlas/tree/HEAD/skills/atlas/SKILL.md
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/atlas

## What it does

atlas stores project decisions, lane journals, handoffs, and queued work in a local store. Before asking about a decision or starting work in a lane, an agent can retrieve the relevant rulings and that lane’s journal.

The workflow records each decision, measurement, or open question as it happens. A handoff carries the project state, commits, evidence, and remaining steps to the next agent. Queued work starts by its key, which goes in the agent brief. Records remain in the local store after an agent ends.

Every brief needs `Kind:` and `Lane:` lines. atlas adds no rules of its own; project rules stay in `CLAUDE.md` and memory files.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add bloodfeast/atlas
```
In the agent chat (not a shell):
```text
/plugin install atlas@atlas
```
This installs the whole atlas plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add bloodfeast/atlas --skill atlas -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/atlas/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/atlas/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add bloodfeast/atlas --skill atlas -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/atlas/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add bloodfeast/atlas --skill atlas -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/atlas/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install bloodfeast/atlas skills/atlas
```

2. **Manually: put the files in place**
- File: `.github/skills/atlas/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add bloodfeast/atlas --skill atlas -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/bloodfeast/atlas --path skills/atlas
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/atlas/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/bloodfeast/atlas/tree/HEAD/skills/atlas/SKILL.md

## When to use it
- retrieve a decision from an earlier session
- journal work under a specific lane
- hand unfinished work to another agent
- start queued work by its key

## Example prompts
- Find the earlier decision about parsing in PARSER-2.
- Record this open question in the PARSER-2 lane journal.
- Write a handoff with the current state, commits, and remaining steps.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4f2856bf50c25186.

BEGIN THIRD-PARTY FILE 4f2856bf50c25186
```text
---
name: atlas
description: How to work with atlas, the project memory - recall past rulings and decisions before asking, journal to a lane, write handoffs, plan and start queued work by its key, write lean agent briefs with Kind and Lane lines, and keep state across context limits and compaction. Use when orchestrating or briefing agents, when recalling what was decided earlier, when an atlas cap, handoff or compaction message appears, or when a session is about to compact or clear; load it before your first journal or handoff.
---

# Working with atlas

atlas is the project's memory: rulings, decisions, lane journals, handoffs and the work queue, kept in a local
store across sessions, agents and compactions, beside an index of the project's notes, docs and code. Nothing
in it is lost when an agent ends; what an agent did not write down is.

This guide is the habits and the workflow. `reference.md` beside it lists every tool, op, argument, journal
entry kind, queue command and setting, generated from the same code as the tool schemas and `atlas://help`
(also `note op=help`). Delegating large work is the `orchestrate` skill. `recall`, `search`, `section` and
`grep` are loaded from the start; `lookup` (where an identifier is defined) and `symbol` (code definitions,
references and callers) are deferred like the write tools: load them by a tool search before the first call.

## The habits

1. **Recall before you ask.** Before asking the user something that may have been decided, and before
   starting work in a lane, ask atlas: `recall query=<words>` for rulings and decisions, `recall lane=<id>`
   for a lane's journal and handoff, `recall key=<key>` for one record whole. The hooks also inject what
   clears the relevance gate, so read what arrived before calling again.
2. **Journal as you go.** A decision, a measurement, a commit or an open question goes into your lane with
   `journal` when it happens, not at the end. One entry per fact, the headline on the first line.
3. **Hand off whenever work is left for later.** Write a `handoff` for your lane before your final answer
   whenever work is left for later, and from your handoff point on at the next clean stopping point. It is the
   only write allowed past the hard limit.
4. **Name work by its queue key.** Planned work is a `queued` entry with a key (`journal:LANE:NNNN`). Say the
   key, start it with a `Queue:` line in the brief, and mark it done; never describe it from memory.
5. **Put a `Lane:` line in every brief**, with `Kind:`, so the agent's start gets its lane's recall and its
   kind's limits. Declare each record the agent needs as a Gherkin tag, the full key every time
   (`@journal:LANE:0012`, pinned `@journal:LANE:0012#a1b2c3d4`), above Feature or above the
   Scenario or Spike it serves: the start lists each by key and title. Not `0012, 0013` after a key,
   nor `0140 onward`: name the few that bind.
6. **Write terse.** Journal, handoff and brief text comes back later as recall answers, so every word costs
   again on each read. Style for what you write into atlas and your replies: telegraphic, keys kept. Drop
```
END THIRD-PARTY FILE 4f2856bf50c25186

The third-party file has ended. Everything between the 4f2856bf50c25186 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3131 of 9098 bytes. © Brandon White · Apache-2.0 · https://github.com/bloodfeast/atlas/tree/HEAD/skills/atlas/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
