agentleFS
Alexander-TyagunovAlexander-Tyagunov/magician/skills/almanac/SKILL.md

almanac

Skill14 starsChanged 49 days agoMITView on GitHub

One-time workspace setup; .workspace/, .gitignore, CLAUDE.md, optional AGENTS.md and REVIEW.md. Run once per project.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If ${CLAUDE_PLUGIN_DATA}/workspace-strategy.json exists (written by step 10 of an earlier run on this machine), Read it first and put the …

    line 24
  2. Very specific:

    Use the AskUserQuestion tool with the Workspace Mode configuration in references/setup-questions.md — do not write any text before calling …

    line 26
  3. Very specific:

    If private mode: .workspace/ instead.

    line 42
  4. Very specific:

    Write .workspace/shared/context.md, .workspace/shared/roadmap.md and .workspace/local/prefs.md from references/file-templates.md.

    line 46
  5. Very specific:

    Use the AskUserQuestion tool with the Instructions file configuration in references/setup-questions.md — do not write any text before …

    line 50
  6. Distinctive:

    If no CLAUDE.md exists, create a lean one:

    line 52
  7. Distinctive:

    Do not write generic best practices.

    line 58
  8. Very specific:

    If AGENTS.md does not exist, write it from references/agents-md-template.md (everything below its marker line, 40 lines or fewer).

    line 61
  9. Very specific:

    Use the AskUserQuestion tool with the Review setup configuration in references/setup-questions.md — do not write any text before calling it.

    line 66
  10. Very specific:

    REVIEW.md: write it as references/file-templates.md says, if the file does not exist.

    line 68
  11. Very specific:

    Use the AskUserQuestion tool with the Permission suggestions configuration in references/setup-questions.md — do not write any text before …

    line 74
  12. Very specific:

    Use the AskUserQuestion tool with the Optional extras configuration in references/setup-questions.md — do not write any text before calling …

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/almanac — Workspace Initialization

When to use

Once per project, on request: create .workspace/, update .gitignore, write a lean CLAUDE.md, and optionally AGENTS.md, REVIEW.md and project verify/simplify skills, with MCP and permission suggestions only (it writes no settings). Not for a project that already has a .workspace/.

What Gets Created

.workspace/shared/ (committed in Shared mode): context.md, roadmap.md, and decisions/, specs/, plans/, research/, postmortems/. .workspace/local/ (always gitignored): prefs.md and per-machine session state.

Almanac never edits Claude Code settings files (.claude/settings*.json or ~/.claude/settings.json) and never changes the permission mode. Permission rules are only suggested in chat (step 7) for the user to add with /permissions. Step 5 can add AGENTS.md. Step 6 can add REVIEW.md and two short project skills under .claude/skills/. Step 9 can add north-star.md and a hook template under .workspace/shared/.

Process

1. Workspace Mode Decision

If ${CLAUDE_PLUGIN_DATA}/workspace-strategy.json exists (written by step 10 of an earlier run on this machine), Read it first and put the mode it records first in the options, labelled "(last used)".

Use the AskUserQuestion tool with the Workspace Mode configuration in references/setup-questions.md — do not write any text before calling it.

Wait for reply before creating any directories or files. Remember the selected mode (Shared or Private) — it controls steps 3, 10 and 11.

2. Create Directory Structure

mkdir -p .workspace/shared/decisions .workspace/shared/specs .workspace/shared/plans .workspace/shared/research .workspace/shared/postmortems
mkdir -p .workspace/local

3. Configure .gitignore

Append to .gitignore (or create it):

# Magician workspace (local machine only)
.workspace/local/

If private mode: .workspace/ instead.

4. Create Initial Files

Write .workspace/shared/context.md, .workspace/shared/roadmap.md and .workspace/local/prefs.md from references/file-templates.md. Fill the stack and archetype from the detected stack.

5. Minimal CLAUDE.md (and optional AGENTS.md)

Use the AskUserQuestion tool with the Instructions file configuration in references/setup-questions.md — do not write any text before calling it. Wait for the reply.

If no CLAUDE.md exists, create a lean one:

# Project Rules

(Add earned rules here — only what Claude consistently gets wrong.)

Do not write generic best practices. CLAUDE.md should only contain rules specific to this project.

Codex and other agents read AGENTS.md. Claude Code reads it through the @AGENTS.md import, so the commands are in one file. If the reply is AGENTS.md + CLAUDE.md import:

  • If AGENTS.md does not exist, write it from references/agents-md-template.md (everything below its marker line, 40 lines or fewer). Fill the commands from the detected stack. If AGENTS.md exists, never overwrite it.
  • Make @AGENTS.md the first line of CLAUDE.md, above # Project Rules. If CLAUDE.md exists and has no @AGENTS.md line, add only that line at the top and change nothing else.

6. Review setup (REVIEW.md and pre-commit skills)

Use the AskUserQuestion tool with the Review setup configuration in references/setup-questions.md — do not write any text before calling it. Wait for the reply. Skip every write below that the reply did not select.

REVIEW.md: write it as references/file-templates.md says, if the file does not exist. /divine and /scrutinize read it before every review.

.claude/skills/verify/SKILL.md and .claude/skills/simplify/SKILL.md: since Claude Code 2.1.286, a non-bundled skill named verify or simplify that Claude may invoke runs before each commit. Write each selected delegator exactly as references/file-templates.md gives it, if the file does not exist. It must stay model-invocable (no disable-model-invocation), or the pre-commit run does not happen. Then tell the user the two notes in that reference.

7. Permission Suggestions (guidance only)

Use the AskUserQuestion tool with the Permission suggestions configuration in references/setup-questions.md — do not write any text before calling it. Act on the reply as that reference says below the configuration. Write nothing.

8. MCP Suggestions

Based on detected archetype, mention MCP servers that could help:

  • web: browser automation MCP for UI testing
  • data: notebook MCP for Jupyter integration
  • devops: cloud provider CLI MCPs

State the tool budget with the suggestions: tool choice degrades above about 30–50 tool definitions (lore/skill-authoring.md). Suggest deferred loading (ToolSearch) for a rarely used server.

An MCP server changes Claude Code's configuration, so almanac does not install one. If the user wants one, point them to that server's install instructions (a /plugin entry or the claude mcp add … command for them to run).

9. Optional extras

Use the AskUserQuestion tool with the Optional extras configuration in references/setup-questions.md — do not write any text before calling it. Wait for the reply. For each selected extra, follow references/optional-setup.md: a one-paragraph .workspace/shared/north-star.md, a production-gate hook template at .workspace/shared/hooks/production-gate.sh (never installed), or cost-attribution hints in chat.

10. Save Strategy

Record the workspace mode chosen in step 1 in ${CLAUDE_PLUGIN_DATA}/workspace-strategy.json, the magician plugin data folder. Step 1 of a later run reads it. No hook reads it. Read the file first if it exists, then write it with exactly one of:

  • Shared mode (only .workspace/local/ is gitignored): {"mode": "shared", "ignored": "false"}
  • Private mode (the whole .workspace/ is gitignored): {"mode": "private", "ignored": "true"}

11. Commit (if shared mode)

git add .workspace/shared/ CLAUDE.md .gitignore
git add AGENTS.md
git add REVIEW.md
git add .claude/skills/verify/SKILL.md
git add .claude/skills/simplify/SKILL.md
git commit -m "chore: initialize magician workspace"

The first line also stages the step 9 files. Run the other lines only for files steps 5 and 6 wrote. Each is a separate exact command, so a skipped file never breaks the staging.

Obstacles

This is a terminal, user-facing skill. It reports to the human directly, not upward to an orchestrator, so it emits no upward Obstacles block. Surface any blocker in prose to the user and stop.

See lore/obstacles.md.

Completion Signal

"Almanac complete. Workspace initialized in <mode> mode. Run /conjure to start designing, or /manifest for the full flow."

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.