Building my first Claude Code Plugin
Source: Dev.to
Introduction
I built a Claude Code plugin for Forgetful.
Forgetful is a semantic memory system I’ve been working on — persistent knowledge that follows you across Claude Code sessions, auto‑linking between related concepts, and the ability to encode repositories into searchable memories. I wrote about it here when I first released it.
I’d been using it daily for weeks, but getting other people set up had friction (MCP configuration, environment variables, picking a database backend). The kind of thing where you send someone a README and never hear from them again.
I even produced some prompt examples as well.
Claude Code plugins seemed like the answer.
If you haven’t used them, see the official docs on Claude Code plugins. They let you extend Claude Code with custom slash commands, agents, skills, and MCP servers. You can bundle a workflow and share it — someone runs /install your-plugin and they’ve got your setup.
That’s what I wanted: one command to get Forgetful running, plus the slash commands I actually use day‑to‑day, packaged so others could try them.
Plugin Commands
The plugin provides the following slash commands:
| Command | Description |
|---|---|
/forgetful-setup | Configures the MCP connection |
/memory-search | Semantic search across your knowledge base |
/memory-save | Create a memory with Zettelkasten constraints (one concept, ≤ 400 words, importance score, proper context) |
/memory-list | Browse recent memories |
/memory-explore | Deep graph traversal; follows links and entities |
/encode-repo | Point it at a codebase and extract memories from it |
In addition, three auto‑activating skills help with:
- deciding when to query vs. create memories,
- curating and linking items properly, and
- exploring the knowledge graph without getting lost.
These aren’t brand‑new ideas; they’re the workflows I was already using, just packaged.
Gotchas & Lessons Learned
Config Files Don’t Survive Updates
The first version shipped an .mcp.json inside the plugin directory. After an update, the plugin directory (~/.claude/plugins/forgetful-plugin@1.0.0/) is wiped, so the config disappeared.
Fix: Do not ship config files inside the plugin. I rewrote /forgetful-setup to run:
claude mcp add forgetful --scope user -- uvx forgetful-aiThis writes to the global ~/.claude.json, which persists across plugin updates. For custom setups (Postgres, remote hosting, auth tokens), the command fetches live docs from GitHub and walks the user through the options, avoiding stale duplicated documentation.
Expensive Commands Need Subagents
/memory-explore performs a five‑phase traversal (query → follow links → find entities → get relationships → pull entity‑linked memories). Running the whole process in the main model quickly fills the context window and incurs high cost.
Solution: Spawn a Haiku subagent to handle the heavy lifting, then return a concise summary. This reduces cost to about a tenth and keeps the main conversation clean. I considered shipping a custom agent, but each agent definition adds to the context window, so I opted for the built‑in general-purpose agent, which is always available and has access to all tools.
Skills Are More Than Fancy Prompts
Initially I thought skills were just markdown prompt files. The missing piece is the YAML front‑matter description, which surfaces to the model and determines when a skill should activate. The model scans these descriptions—not the full file—on each message.
Key takeaways:
- Write a clear, third‑person description that specifies when the skill applies.
- Vague descriptions won’t be triggered.
- The description is not primarily for human readers; it’s the activation trigger.
Trying It Out
/install forgetful-plugin
/forgetful-setupStandard setup takes about 30 seconds.
Links
- Plugin repository:
- Main Forgetful project: