Skip to content
Back to search

claude-spellbook

SkillWorks with Claude CodeGitHub

A curated collection of skills, prompts, and workflows that extend Claude's capabilities — your personal grimoire for AI-powered development.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kid-sid--claude-spellbook/badge.svg)](/listings/kid-sid--claude-spellbook)

HTML

<a href="/listings/kid-sid--claude-spellbook"><img src="/api/listings/kid-sid--claude-spellbook/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install skills into Claude Code

Copy the skills you want into your Claude skills directory:

# Install a single skill
cp -r skills/security ~/.claude/skills/

# Install everything
cp -r skills/* ~/.claude/skills/

Claude Code picks them up automatically on the next session — no restart needed.

2. Install agents

Copy the `.claude/agents/` folder into any project:

cp -r .claude/agents /path/to/your-project/.claude/agents

Or install globally so they're available in every project:

cp -r .claude/agents/* ~/.claude/agents/

3. Install slash commands

Copy the `.claude/commands/` folder into any project you work on:

cp -r .claude/commands /path/to/your-project/.claude/commands

Or install globally into your home Claude directory:

cp -r .claude/commands ~/.claude/commands

4. Install tool configs into a project

Use the installer script to drop configs into any project:

# Single language
bash tools/install.sh node --target /path/to/your-project
bash tools/install.sh python --target /path/to/your-project

# All languages at once
bash tools/install.sh all --target /path/to/your-project

Or use the Makefile shorthand:

make setup TARGET=/path/to/your-project LANG=typescript

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 707 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/logo.png" alt="claude-spellbook logo" width="120" />
  3. # claude-spellbook
  4. **Ship faster. Review smarter. Build with intent.**
  5. A curated library of skills, slash commands, and agents that transform Claude Code
  6. into a precision engineering assistant — one spell at a time.
  7. [![CI](https://github.com/kid-sid/claude-spellbook/actions/workflows/ci.yml/badge.svg)](https://github.com/kid-sid/claude-spellbook/actions/workflows/ci.yml)
  8. ![Skills](https://img.shields.io/badge/skills-65-blueviolet)
  9. ![Commands](https://img.shields.io/badge/slash%20commands-18-blue)
  10. ![License](https://img.shields.io/badge/license-MIT-green)
  11. *Each skill is a spell. Cast wisely.*
  12. </div>
  13. ---
  14. ## What's in the box
  15. | Layer | What | Count |
  16. |---|---|---|
  17. | **Skills** | Structured instruction sets loaded contextually by Claude | 65 |
  18. | **Slash Commands** | One-shot `/commands` for common engineering tasks | 18 |
  19. | **Agents** | Autonomous subprocesses for multi-file, long-running tasks | 7 |
  20. | **Tool Configs** | Drop-in linter/formatter configs for 6 languages | 6 |
  21. | **Templates** | Scaffold starters for Node, TypeScript, Python, Svelte | 4 |
  22. ---
  23. ## Quick Start
  24. ### 1. Install skills into Claude Code
  25. Copy the skills you want into your Claude skills directory:
  26. ```bash
  27. # Install a single skill
  28. cp -r skills/security ~/.claude/skills/
  29. # Install everything
  30. cp -r skills/* ~/.claude/skills/
  31. ```
  32. Claude Code picks them up automatically on the next session — no restart needed.
  33. ### 2. Install agents
  34. Copy the `.claude/agents/` folder into any project:
  35. ```bash
  36. cp -r .claude/agents /path/to/your-project/.claude/agents
  37. ```
  38. Or install globally so they're available in every project:
  39. ```bash
  40. cp -r .claude/agents/* ~/.claude/agents/
  41. ```
  42. ### 3. Install slash commands
  43. Copy the `.claude/commands/` folder into any project you work on:
  44. ```bash
  45. cp -r .claude/commands /path/to/your-project/.claude/commands
  46. ```
  47. Or install globally into your home Claude directory:
  48. ```bash
  49. cp -r .claude/commands ~/.claude/commands
  50. ```
  51. ### 4. Install tool configs into a project
  52. Use the installer script to drop configs into any project:
  53. ```bash
  54. # Single language
  55. bash tools/install.sh node --target /path/to/your-project
  56. bash tools/install.sh python --target /path/to/your-project
  57. # All languages at once
  58. bash tools/install.sh all --target /path/to/your-project
  59. ```
  60. Or use the Makefile shorthand:
  61. ```bash
  62. make setup TARGET=/path/to/your-project LANG=typescript
  63. ```
  64. ---
  65. ## Skills
  66. Skills are markdown files that Claude loads when a relevant task is triggered. They encode judgment, checklists, and domain knowledge — turning Claude from a general assistant into a specialist for a specific phase of your workflow.
  67. ### How skills activate
  68. When you describe a task, Claude matches it against the **"When to Activate"** section in each skill. You don't invoke them manually — they're loaded automatically based on context.
  69. > Example: start a conversation about "designing a REST API for user authentication" and the `api-design` skill loads. Ask Claude to "write a Dockerfile for this service" and `containerization` loads.
  70. ### Skill inventory
  71. #### AI & Agents
  72. | Skill | Activates when… |
  73. |---|---|
  74. | `agentex` | Building ACP agents (sync/async/Temporal), working with manifests, ADK modules, or agent types |
  75. | `temporal` | Writing Temporal workflows, activities, signals, or debugging determinism and failure handling |
  76. | `general-temporal` | Building or debugging Temporal workflows in Python using the standard temporalio SDK — determinism, retries, signals, state, versioning |
  77. | `langgraph` | Building StateGraph pipelines, conditional routing, tool calling, checkpointers, or interrupts |
  78. | `openai-agents` | Defining agents, `@function_tool`, handoffs, streaming, guardrails, or Agentex ADK integration |
  79. #### Languages & Frameworks
  80. | Skill | Activates when… |
  81. |---|---|
  82. | `go` | Error handling patterns, goroutines/channels, context propagation, interface composition, generics, or table-driven tests |
  83. | `python` | Advanced type hints, async pitfalls, decorators, generators, or pattern matching |
  84. | `typescript` | Utility types, conditional/mapped types, discriminated unions, branded types, or `satisfies` |
  85. | `fastapi` | Structuring FastAPI apps, Depends injection, Pydantic v2 schemas, error handling, or testing routes |
  86. | `pydantic` | Deep `field_validator`/`model_validator`, `Annotated` constraints, serialization, generic models, or `pydantic-settings` |
  87. | `sqlalchemy` | Async SQLAlchemy 2.0 `Mapped` models, session management, joins, relationships, or Alembic migrations |
  88. | `mongodb` | Motor async CRUD, aggregation pipelines, index design, transactions, or `adk.state` patterns |
  89. | `postgresql` | Window functions, CTEs, JSONB queries, index design, `EXPLAIN ANALYZE`, or schema migrations |
  90. | `redis` | Choosing data structures, caching strategies, pub/sub, Redis Streams, or distributed locks |
  91. | `websockets-sse` | Real-time server push, LLM token streaming, WebSocket connection management, or Redis broadcast |
  92. #### Requirements & Design
  93. | Skill | Activates when… |
  94. |---|---|
  95. | `requirements-planning` | Writing user stories, PRDs, or acceptance criteria |
  96. | `system-design` | Designing systems, estimating capacity, drawing architecture |
  97. | `api-design` | Designing or reviewing REST endpoints |
  98. | `graphql` | Designing schemas, resolvers, mutations, DataLoader, subscriptions, or securing a GraphQL API |
  99. | `database-design` | Designing schemas, indexes, or migrations |
  100. | `microservices` | Decomposing services, designing async comms, circuit breakers, CQRS |
  101. #### Security & Identity
  102. | Skill | Activates when… |
  103. |---|---|
  104. | `auth` | Implementing login flows, JWTs, OAuth2/OIDC, RBAC/ABAC, or token refresh and revocation |
  105. #### Development
  106. | Skill | Activates when… |
  107. |---|---|
  108. | `coding-standards` | Writing or reviewing code for quality/style |
  109. | `development-workflow` | Branching, PRs, commits, or code review |
  110. | `error-handling` | Designing error hierarchies, retry/backoff logic, structured API errors, or propagating errors across service boundaries |
  111. | `writing-plans` | Creating an implementation plan for a non-trivial task spanning multiple files, migrations, specific sequencing, or subagent handoff |
  112. | `frontend` | Building React components, managing state, data fetching, forms, or optimizing rendering |
  113. | `react` | Advanced hooks, compound components, error boundaries, or TypeScript + React patterns |
  114. | `nextjs` | App Router pages, server/client components, data fetching, layouts, middleware, or deployment |
  115. | `angular` | Signals, standalone components, inject(), NgRx, RxJS patterns, or Angular 17+ control flow |
  116. | `tailwind` | Composing utilities, responsive design, dark mode, cva variants, or custom theme config |
  117. | `event-driven` | Designing Kafka topics, producers/consumers, outbox pattern, DLQs, or event sourcing |
  118. | `webhooks` | Designing webhook delivery, HMAC verification, retry handling, idempotent consumers, or local testing |
  119. | `caching` | Adding Redis, choosing a caching strategy, designing TTLs, or configuring HTTP cache headers |
  120. | `claude-code` | Setting up skills, slash commands, agents, hooks, permissions, MCP servers, or CLAUDE.md |
  121. | `spellbook-setup` | Installing claude-spellbook — global vs project-level, memory_map MCP, hooks, tool configs |
  122. | `memory-map` | Installing memory_map MCP server, session-start CLAUDE.md, memory/history tools, cross-project recall |
  123. | `feature-flags` | Adding feature flag support, designing rollouts or A/B experiments, choosing a flag platform, testing flag-gated code, or managing flag lifecycle |
  124. | `data-pipelines` | Building Airflow DAGs, writing dbt models or tests, designing incremental loads, implementing idempotent ETL/ELT, or validating data quality |
  125. | `github-issues` | Filing bug reports, feature requests, or tasks on GitHub; triaging severity; using the gh CLI; handling regressions, flaky tests, or security vulnerabilities |
  126. | `ui-ux-pro-max` | Designing interfaces, choosing styles, palettes, fonts, or auditing UI/UX design code |
  127. #### Testing
  128. | Skill | Activates when… |
  129. |---|---|
  130. | `unit-testing` | Writing or fixing unit tests |
  131. | `integration-testing` | Testing APIs, databases, or service boundaries |
  132. | `solution-testing` | Writing E2E or BDD tests with Playwright/Gherkin |
  133. | `smoke-testing` | Verifying deployments, gating CI pipelines, or building health-check suites |
  134. | `test-strategy` | Planning test coverage or choosing a testing model |
  135. | `performance-testing` | Load testing with k6 or Locust |
  136. #### Security & Quality
  137. | Skill | Activates when… |
  138. |---|---|
  139. | `security` | Security reviews, threat modeling, auth/secrets |
  140. | `accessibility` | Building or auditing UI for WCAG conformance, ARIA, keyboard nav |
  141. | `claude-api` | Building with the Anthropic SDK or Agent SDK |
  142. | `azure` | Azure SDK auth, Blob Storage, AI Search, Document Intelligence, Key Vault |
  143. | `azure-service-bus` | Queues vs topics/subscriptions, peek-lock, DLQ, sessions, subscription filters, scheduled messages |
  144. | `aws` | boto3/SDK v3 auth, S3, DynamoDB, Lambda, SQS batch, Secrets Manager, IAM least privilege |
  145. | `ai-engineer` | Building RAG systems, LLM agents, vector search, or AI safety patterns |
  146. | `complex-doc-rag` | Ingesting PDFs, Excel, CSV, or images into a RAG pipeline; debugging extraction gaps |
  147. | `promptbase` | Writing, reviewing, or adapting a skill for PromptBase sale — scope, audience, rejection risk, listing copy, examples, setup |
  148. #### CI/CD & Infrastructure
  149. | Skill | Activates when… |
  150. |---|---|
  151. | `ci-cd` | Writing GitHub Actions workflows or quality gates |
  152. | `containerization` | Writing Dockerfiles, Compose, or Kubernetes configs |
  153. | `docker` | Writing Dockerfiles, multi-stage builds, Compose networking, health checks, or debugging containers |
  154. | `infrastructure-as-code` | Working with Terraform modules or environments |
  155. #### Deployment & Operations
  156. | Skill | Activates when… |
  157. |---|---|
  158. | `deployment-strategies` | Planning rollouts, canary deploys, or rollbacks |
  159. | `observability` | Adding logging, metrics, or distributed tracing |
  160. | `performance` | Profiling, caching, or fixing N+1 queries |
  161. | `incident-response` | Responding to, documenting, or learning from incidents |
  162. | `technical-documentation` | Writing READMEs, OpenAPI specs, or tech specs |
  163. ---
  164. ## Agents
  165. Agents are autonomous subprocesses that run in their own context window with their own tool permissions. Unlike slash commands (which run inline and can pollute the main conversation), agents are isolated — ideal for tasks that span many files, run in parallel, or need a fresh context.
  166. Agents live in `.claude/agents/` and are invoked automatically when Claude decides to delegate based on the agent's `description`.
  167. ### When agents beat slash commands
  168. | Use case | Use `/command` | Use agent |
  169. |---|---|---|
  170. | Review current git diff | `/review` | — |
  171. | Audit an entire service (40+ files) | — | `security-auditor` |
  172. | Generate tests for one function | `/test-gen` | — |
  173. | Generate tests for a whole module | — | `test-coverage-agent` |
  174. | Explain a single file | `/explain` | — |
  175. | Check one manifest for outdated deps | manual `npm audit` | — |
  176. | Audit deps across a multi-stack repo | — | `dependency-auditor` |
  177. | Write a new-joiner guide | — | `onboarding-agent` |
  178. | Full PR review (spec + quality) | — | `code-reviewer` |
  179. | Verify spec only, defer quality | — | `code-reviewer-spec` |
  180. | Quality pass after spec confirmed | — | `code-reviewer-quality` |
  181. ### Available agents
  182. #### `security-auditor`
  183. Scans a full codebase for OWASP Top 10 vulnerabilities: hardcoded secrets, injection flaws, broken auth, weak crypto, security misconfiguration, vulnerable dependencies, and data exposure.
  184. **Tools:** `Read`, `Grep`, `Glob`, `Bash` · **Model:** Sonnet · **Color:** Red
  185. ```
  186. Audit the src/ directory for security vulnerabilities
  187. Do a full security review of this codebase
  188. Security scan everything under services/payments
  189. ```
  190. > Reads context around every match before reporting — grep false positives are discarded silently.
  191. #### `code-reviewer`
  192. Performs a deep pull request review covering logic correctness, code quality, security, test coverage, and performance. Reads full files (not just diff hunks) and follows symbols cross-file to catch invariant breaks, missing migrations, and unhandled callers.
  193. **Tools:** `Read`, `Grep`, `Glob`, `Bash` · **Model:** Sonnet · **Color:** Blue
  194. ```
  195. Review this PR in depth
  196. Do a thorough review of the changes in src/payments/
  197. Review PR 84 — it touches the auth layer
  198. ```
  199. #### `code-reviewer-spec`
  200. Stage 1 review only — verifies a change fully implements its stated requirements. Checks for missing pieces, scope creep, and gaps between the stated intent and the actual diff. Use before a quality pass.
  201. **Tools:** `Read`, `Grep`, `Glob`, `Bash` · **Model:** Sonnet · **Color:** Blue
  202. ```
  203. Check if this change actually implements what was asked
  204. Verify the spec is fully covered before we merge
  205. Does this PR match the requirements in the ticket?
  206. ```
  207. #### `code-reviewer-quality`
  208. Stage 2 review only — evaluates code quality, security, performance, and test coverage after spec compliance has been confirmed. Use after `code-reviewer-spec` gives the green light.
  209. **Tools:** `Read`, `Grep`, `Glob`, `Bash` · **Model:** Sonnet · **Color:** Blue
  210. ```
  211. Quality review of this PR — spec is already confirmed
  212. Check for code smells, security issues, and missing tests
  213. Performance and coverage review on src/payments/
  214. ```
  215. #### `dependency-auditor`
  216. Scans all dependency manifests across a repository (`package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, and more), runs ecosystem audit tools (`npm audit`, `pip-audit`, `cargo audit`, `govulncheck`), and produces a unified report covering vulnerabilities, unpinned versions, missing lock files, and abandoned packages.
  217. **Tools:** `Read`, `Grep`, `Glob`, `Bash` · **Model:** Sonnet · **Color:** Orange
  218. ```
  219. Audit all dependencies in this monorepo
  220. Check for vulnerable packages across the whole project
  221. Find outdated and unpinned dependencies
  222. ```
  223. #### `test-coverage-agent`
  224. Analyses source files across a module, maps them against existing tests to find untested code paths, then writes the missing tests — following the project's existing framework, assertion library, and file naming conventions. Runs the new tests to verify they pass before finishing.
  225. **Tools:** `Read`, `Grep`, `Glob`, `Bash`, `Write` · **Model:** Sonnet · **Color:** Green
  226. ```
  227. Generate tests for everything under src/payments/
  228. Find and fill coverage gaps in the auth module
  229. Add missing tests across the whole services/ directory
  230. ```
  231. #### `onboarding-agent`
  232. Reads the entire repository — structure, stack, routes, schemas, CI config, Makefile, environment variables, and git history — then writes an `ONBOARDING.md` covering what the service does, local setup, architecture overview, key files, env var reference, gotchas, and who to ask for what.
  233. **Tools:** `Read`, `Grep`, `Glob`, `Bash`, `Write` · **Model:** Sonnet · **Color:** Purple
  234. ```
  235. Write an onboarding guide for this repo
  236. Generate a new-joiner doc for a backend engineer joining next week
  237. Create an ONBOARDING.md for this service
  238. ```
  239. ---
  240. ## Slash Commands
  241. Slash commands are one-shot prompts you run with `/command-name` in Claude Code. They're stored in `.claude/commands/` and show up in the `/` menu automatically once installed.
  242. | Command | What it does |
  243. |---|---|
  244. | `/review` | Reviews staged/unstaged changes or a PR for quality and security issues |
  245. | `/changelog` | Generates a changelog from git history since the last release tag |
  246. | `/security-scan` | Audits code against OWASP Top 10 and the security skill checklist |
  247. | `/test-gen` | Generates unit and integration tests for a file or function |
  248. | `/explain` | Explains a file, function, or architectural pattern in depth |
  249. | `/refactor` | Analyzes code smells and suggests or applies refactoring |
  250. | `/scaffold` | Scaffolds a new service with production-ready boilerplate |
  251. | `/deploy-check` | Runs a pre-deployment verification checklist |
  252. | `/adr` | Generates an Architecture Decision Record from a discussion |
  253. | `/postmortem` | Generates a postmortem document from an incident description |
  254. | `/prd` | Generates a Product Requirements Document pre-filled from context |
  255. | `/mem_save` | Manually checkpoints the current conversation to `.mcp_history.json` |
  256. | `/skill-validate` | Runs all CI format checks locally — skills, agents, badge sync, inventory |
  257. | `/create-issue` | Creates one or more GitHub issues from a natural language description |
  258. | `/resolve-issue` | Fetches a GitHub issue, applies the fix, comments what changed, and closes it |
  259. | `/update-skill` | Reviews pending findings (web discoveries, bugs, gaps) and applies approved changes to the relevant skill file |
  260. | `/roast-repo` | Delivers a brutally honest, technically sharp roast of the current repo — real bugs, smells, security holes, each with a fix |
  261. ### Usage examples
  262. ```
  263. # Review your current git diff
  264. /review
  265. # Review a specific pull request
  266. /review 42
  267. # Generate tests for a specific file
  268. /test-gen src/auth/middleware.ts
  269. # Scaffold a new Python API service
  270. /scaffold python-api payments-service
  271. # Generate a changelog since the last release tag
  272. /changelog
  273. # Generate a changelog for a specific new version
  274. /changelog v2.1.0
  275. # Create an ADR for a recent decision
  276. /adr We chose Postgres over MongoDB because our data is highly relational
  277. ```
  278. ---
  279. ## Tool Configs
  280. Drop-in configuration files for linters and formatters. Consistent settings across all your projects, managed from one place.
  281. | Language | Tools included |
  282. |---|---|
  283. | `node` | prettier, eslint, markdownlint |
  284. | `typescript` | tsc (strict), prettier, eslint |
  285. | `svelte` | SvelteKit, vite, prettier-plugin-svelte, eslint-plugin-svelte |
  286. | `python` | black, ruff |
  287. | `go` | golangci-lint (gofmt ships with Go) |
  288. | `rust` | rustfmt, clippy, rust-toolchain |
  289. ### Installing into a project
  290. ```bash
  291. # Node project
  292. bash tools/install.sh node --target ~/projects/my-app
  293. # TypeScript project
  294. bash tools/install.sh typescript --target ~/projects/my-api
  295. # Python project
  296. bash tools/install.sh python --target ~/projects/my-service
  297. # Rust project
  298. bash tools/install.sh rust --target ~/projects/my-crate
  299. # Everything
  300. bash tools/install.sh all --target ~/projects/monorepo
  301. ```
  302. > Files that already exist (e.g. `pyproject.toml`) are skipped with a warning pointing to the source — so you can manually merge without losing your customizations.
  303. ### Development commands (for working on the spellbook itself)
  304. ```bash
  305. make install # Install Node + Python tools locally
  306. make check # Check which tools are available on your PATH
  307. make format # Run prettier over all skill markdown files
  308. make lint # Run markdownlint over all skill markdown files
  309. make help # List all available make targets
  310. ```
  311. ---
  312. ## Hooks
  313. The project ships a `settings.local.json` with Claude Code hooks that run automatically on every file write, edit, or bash command. Install them by copying into your project's `.claude/` directory.
  314. ### PostToolUse — skill finding capture
  315. When Claude uses `WebSearch` or `WebFetch`, a hook appends the query/URL and a result snippet to `.claude/findings.jsonl`. Run `/update-skill` to review and apply findings back to skill files. Claude also writes `bug` and `gap` entries inline when it spots incorrect or missing content in an active skill.
  316. | Trigger | Hook |
  317. |---|---|
  318. | `WebSearch` / `WebFetch` | Appends `{source:"web", ...}` entry to `.claude/findings.jsonl` |
  319. ### PostToolUse — auto-format on write/edit
  320. | Trigger | Hook |
  321. |---|---|
  322. | Write `**/*.ts`, `**/*.svelte` | `prettier --write` |
  323. | Write `**/*.py` | `black` |
  324. | Write `**/*.go` | `gofmt -w` |
  325. | Write `**/*.rs` | `rustfmt` |
  326. | Edit `**/*.ts`, `**/*.svelte` | `eslint --fix` |
  327. | Edit `**/*.py` | `ruff check --fix` |
  328. | Edit `**/*.go` | `golangci-lint run` |
  329. | Edit `**/*.rs` | `cargo clippy --fix` |
  330. | Edit `**/*.md` | `markdownlint --fix` |
  331. | Edit `skills/*/skill.md` | Skill format validator (frontmatter, sections, checklist) |
  332. ### PostToolUse — bash command log
  333. Every bash command is logged to `.claude/command.log` asynchronously — useful for auditing what Claude ran during a session.
  334. ### PreToolUse — safety guards
  335. | Guard | What it blocks |
  336. |---|---|
  337. | `git push --force` (without `--force-with-lease`) | Blocked with an error |
  338. | `rm -rf` | Allowed but prints a warning with the command |
  339. ### Session lifecycle hooks
  340. | Event | Hook |
  341. |---|---|
  342. | `SessionStart` | Runs `git status` at the start of every session |
  343. | `UserPromptSubmit` | Runs `memory-map-hook` every message — saves conversation history |
  344. | `PreCompact` | Runs `memory-map-hook --force` before context compaction |
  345. | `Stop` | Runs `memory-map-hook --force` async on session end — final checkpoint |
  346. > These hooks live in `~/.claude/settings.json` (global) so they fire in every project. See the MCP Server section for the full config.
  347. ---
  348. ## MCP Server
  349. Persistent memory and conversation history are provided by the standalone [memory_map](https://github.com/kid-sid/memory_map) repo. It gives Claude a key-value memory store and rolling conversation history that persist across sessions.
  350. ### Tools exposed
  351. | Tool | What it does |
  352. |---|---|
  353. | `load_memory` / `save_memory` / `delete_memory` | Per-project key-value context store |
  354. | `suggest_history` | Primary session-start tool — hybrid retrieval (vector + BM25 + RRF + MMR) within a token budget |
  355. | `save_history` / `load_history` / `get_history_chunks` | Save chunks (auto-called by hooks); inspect tag index; fetch full dialogue by ID |
  356. | `load_global_memory` / `save_global_memory` | User-level facts shared across all projects |
  357. | `get_local_structure` | Local directory tree (gitignore-aware) |
  358. | `get_github_structure` | GitHub repo file tree |
  359. | `get_git_history` | Recent commits |
  360. | `set_compression` | Output compression level (0=raw, 1=compact, 2=dense) |
  361. ### Setup (one-time)
  362. **Step 1 — Install**
  363. ```bash
  364. # Recommended — bundles the OpenAI client for semantic history search
  365. pip install "memory-map-mcp[embed-openai]"
  366. # Base install — works fine if you stick with local embeddings or BM25 only
  367. pip install memory-map-mcp
  368. ```
  369. > The `[embed-openai]` extra pulls in the OpenAI SDK so `MEMORY_MAP_EMBED_PROVIDER=openai` works without manual installs. It does **not** make `OPENAI_API_KEY` mandatory at install time — only when you actually use the OpenAI provider.
  370. **Step 2 — Set up MongoDB** (required for conversation history)
  371. You need a MongoDB instance. Two options:
  372. - **Free Atlas cluster** (recommended — no install): [mongodb.com/cloud/atlas/register](https://www.mongodb.com/cloud/atlas/register) → create a free M0 cluster → get the connection string from "Connect → Drivers"
  373. - **Local MongoDB**: [mongodb.com/try/download/community](https://www.mongodb.com/try/download/community) → install → URI is `mongodb://localhost:27017`
  374. > Key-value memory (`save_memory` / `load_memory`) works **without** MongoDB and falls back to a local file. Only conversation history requires a live connection.
  375. **Step 2b — Configure environment variables**
  376. The most reliable way is to export from your shell profile so the vars are available everywhere:
  377. **Mac/Linux** — add to `~/.zshrc` or `~/.bashrc`:
  378. ```bash
  379. export MEMORY_MAP_MONGO_URI="mongodb+srv://<user>:<password>@<cluster>.mongodb.net"
  380. # Optional: OpenAI vector search (semantic similarity in history retrieval)
  381. # export MEMORY_MAP_EMBED_PROVIDER=openai
  382. # export OPENAI_API_KEY=sk-...
  383. # Optional: local CPU vector search (no API key needed)
  384. # export MEMORY_MAP_EMBED_PROVIDER=local
  385. ```
  386. **Windows** — add to your PowerShell profile (`$PROFILE`):
  387. ```powershell
  388. $env:MEMORY_MAP_MONGO_URI = "mongodb+srv://<user>:<password>@<cluster>.mongodb.net"
  389. ```
  390. Or use System Properties → Environment Variables for a permanent GUI-based setting.
  391. Alternatively, create a `.env` file in **each project root** — `memory-map-mcp` picks it up automatically when Claude Code opens that project:
  392. ```bash
  393. MEMORY_MAP_MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net
  394. ```
  395. **Step 3 — Register globally** (available in all projects, not just one)
  396. ```bash
  397. claude mcp add -s user memory_map -- memory-map-mcp
  398. ```
  399. **Step 4 — Add hooks to `~/.claude/settings.json`** so history saves in every project automatically
  400. ```json
  401. {
  402. "hooks": {
  403. "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "memory-map-hook", "timeout": 10 }] }],
  404. "PreCompact": [{ "matcher": "", "hooks": [{ "type": "command", "command": "memory-map-hook --force", "timeout": 15 }] }],
  405. "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "memory-map-hook --force", "timeout": 15, "async": true }] }]
  406. }
  407. }
  408. ```
  409. **Step 5 — Enable memory for a project**
  410. Add this to the `CLAUDE.md` in any project you want Claude to remember:
  411. ```markdown
  412. ## Session Start (Required)
  413. At the start of every session, before doing anything else:
  414. 1. Call `load_memory` with the current working directory
  415. 2. Call `suggest_history` with the current working directory and the user's first message
  416. 3. Read both outputs before exploring files or asking questions
  417. ```
  418. Claude reads `CLAUDE.md` at session start and loads memory and history automatically.
  419. ### Usage
  420. Use `/mem_save` at any time to manually checkpoint the current conversation. Memory is stored in MongoDB (primary) or `.mcp_memory.json` per project (fallback). History is stored in the `memory_map.history` MongoDB collection.
  421. Full documentation: [github.com/kid-sid/memory_map](https://github.com/kid-sid/memory_map)
  422. ---
  423. ## CI / Workflows
  424. Two GitHub Actions workflows keep the spellbook healthy:
  425. ### `ci.yml` — runs on every push and PR to `main`
  426. | Job | What it checks |
  427. |---|---|
  428. | **Validate Skill Format** | Every `skills/*/skill.md` has frontmatter (`name`, `description`), a `## When to Activate` section, a `## Checklist` section, and at least one `- [ ]` item |
  429. | **Lint Markdown** | All `.md` files pass markdownlint |
  430. | **Validate Tool Configs** | `tools/install.sh` parses cleanly; all 6 language tool directories and key config files are present |
  431. | **Validate Slash Commands** | Every `.claude/commands/*.md` is non-empty |
  432. | **Check Cross-References** | Logs how many other skills reference each skill (informational) |
  433. ### `release.yml` — runs on version tags (`v*`)
  434. Creates a GitHub Release with an auto-generated changelog and a summary of how many skills, agents, commands, and tool configs are in the release.
  435. ```bash
  436. # Create a release
  437. git tag v1.2.0
  438. git push origin v1.2.0
  439. ```
  440. ---
  441. ## Repository Structure
  442. ```
  443. claude-spellbook/
  444. ├── skills/<name>/skill.md — skill reference files
  445. ├── .claude/agents/ — autonomous subagents
  446. ├── .claude/commands/ — slash command definitions
  447. ├── .claude/settings.local.json
  448. ├── tools/ — linter/formatter configs + install.sh
  449. ├── templates/ — scaffold starters
  450. ├── .github/workflows/ — CI + release
  451. ├── CLAUDE.md
  452. └── Makefile
  453. ```
  454. ---
  455. ## Writing a New Skill
  456. Every skill follows a strict format enforced by CI. Read `CLAUDE.md` for the full spec, or use `api-design` and `claude-api` as canonical examples.
  457. ```markdown
  458. ---
  459. name: kebab-case-name
  460. description: One dense keyword-rich sentence.
  461. ---
  462. # Title
  463. One-sentence intro.
  464. ## When to Activate
  465. - Verb-leading trigger condition
  466. - ...
  467. ## Content sections...
  468. ## Checklist
  469. - [ ] At least 8 items
  470. ```
  471. To add a new skill:
  472. 1. Create `skills/<name>/skill.md` following the format above
  473. 2. Add an entry to the skill inventory table in `CLAUDE.md` and `README.md`
  474. 3. Open a PR — CI will validate the format automatically
  475. To propose a skill without writing it, open an issue using the **New Skill Request** template.
  476. ---
  477. ## Writing a New Agent
  478. Agents live at `.claude/agents/<name>.md`. The file body is a system prompt — write it in second person.
  479. ```markdown
  480. ---
  481. name: kebab-case-name
  482. description: One sentence — when to delegate to this agent vs. a slash command.
  483. tools: Read, Grep, Glob, Bash # minimum required
  484. model: sonnet # sonnet | opus | haiku | inherit
  485. color: red # red | blue | green | yellow | purple | orange
  486. ---
  487. You are a … agent. Your job is to …
  488. ## Methodology
  489. …
  490. ## Output Format
  491. …
  492. ```
  493. Restrict `tools` to the minimum needed — a read-only agent must not have `Write` or `Edit`. After adding, update the Agent Inventory in `CLAUDE.md` and `README.md`.
  494. ---
  495. ## Contributing
  496. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full guide — branch naming, commit conventions, skill/agent format rules, and the PR process.
  497. Quick reference:
  498. 1. Fork and branch: `feat/skill-<name>`, `feat/agent-<name>`, or `fix/<issue>`
  499. 2. Follow the format — CI catches errors automatically
  500. 3. Fill in the PR template
  501. 4. Conventional commits: `feat:`, `fix:`, `docs:`, `chore:`
  502. ---
  503. ## Star History
  504. [![Star History Chart](https://api.star-history.com/svg?repos=kid-sid/claude-spellbook&type=Date)](https://star-history.com/#kid-sid/claude-spellbook&Date)
  505. ---
  506. ## License
  507. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.