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
- ryanmaclean/skillstheir own version, first seen Sep 23, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- ryanmaclean/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- accelerateSkill
- autopsySkill
- blueprintSkill
- certifySkill
- chronicleSkill
- confluenceSkill
- conjureSkill
- deploySkill
- divineSkill
- inscribeSkill
- jiraSkill
- knowledge-graphSkill
- magicSkill
- manifestSkill
- orchestrateSkill
- portalSkill
- scrutinizeSkill
- sealSkill
- sentinelSkill
- statuslineSkill
- transmuteSkill
- unravelSkill
- wardSkill
- weaveSkill
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
- Very specific: line 24
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 …
- Very specific: line 26
Use the AskUserQuestion tool with the Workspace Mode configuration in references/setup-questions.md — do not write any text before calling …
- Very specific: line 42
If private mode: .workspace/ instead.
- Very specific: line 46
Write .workspace/shared/context.md, .workspace/shared/roadmap.md and .workspace/local/prefs.md from references/file-templates.md.
- Very specific: line 50
Use the AskUserQuestion tool with the Instructions file configuration in references/setup-questions.md — do not write any text before …
- Distinctive: line 52
If no CLAUDE.md exists, create a lean one:
- Distinctive: line 58
Do not write generic best practices.
- Very specific: line 61
If AGENTS.md does not exist, write it from references/agents-md-template.md (everything below its marker line, 40 lines or fewer).
- Very specific: line 66
Use the AskUserQuestion tool with the Review setup configuration in references/setup-questions.md — do not write any text before calling it.
- Very specific: line 68
REVIEW.md: write it as references/file-templates.md says, if the file does not exist. - Very specific: line 74
Use the AskUserQuestion tool with the Permission suggestions configuration in references/setup-questions.md — do not write any text before …
- Very specific: line 88
Use the AskUserQuestion tool with the Optional extras configuration in references/setup-questions.md — do not write any text before calling …
≈ “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.
Files
/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/local3. 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.mddoes not exist, write it fromreferences/agents-md-template.md(everything below its marker line, 40 lines or fewer). Fill the commands from the detected stack. IfAGENTS.mdexists, never overwrite it. - Make
@AGENTS.mdthe first line ofCLAUDE.md, above# Project Rules. IfCLAUDE.mdexists and has no@AGENTS.mdline, 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."
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
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.

