Cookbook — Turn concepts into real results¶
You do not need to read this Cookbook in one sitting. Pick one result you want, copy its first action, and open the details only when you need the remaining steps.
If these terms are new to you, first return to Stage 5: Claude Code Ecosystem. To compare OpenRouter, Pi, OpenCode, and Ollama, open the Complete CLI Agent Guide.
📌 What this Cookbook helps you do¶
A Recipe is a short route from "What do I want to do?" to "How do I know it is done?" Complete any recipe and you will have something you can check—not just another page you have read:
- A reusable action card.
- A small tool an Agent can call.
- A document, research note, or literature workflow.
- A CLI Agent that runs on your own computer.
You will also see Skill, MCP Server, and Coding Agent. They mean a reusable instruction card, a tool connector for an Agent, and an assistant that reads files, edits them, and checks the result.
🎯 Choose one recipe first¶
| What you want to accomplish | Where to start | Key risks |
|---|---|---|
| Let Claude remember a repeatable method | 1. First Skill | Rules that are too vague |
| Let an Agent call your Python tool | 2. First MCP server | Giving the tool too much access |
| Generate Word, Excel, PowerPoint, or PDF files | 3. Office Docs Workflow | Failing to open and inspect the result |
| Get cited answers from your own sources | 4. Gemini Notebook Workflow | A Community Integration—a bridge maintained by users—may stop working |
| Search or organize Zotero items | 5. Zotero Workflow | Writing changes without a preview |
| Use a local model to help edit code | 6. Local LLM + CLI Agent | A model or computer that is too small for the task |
🧩 Six core terms¶
- Recipe: A short route from "What do I want to do" to "How do I know it's done?"
- Skill: Repeatable instructions placed in
SKILL.md. The agent reads it only when needed. - MCP Server: A program that presents code, data, or services as tools, resources, or prompts an Agent can use.
- Community Integration: A bridge made by the community rather than the product team. It may work well, but an upstream change can break it.
- Model Runtime: The program that actually loads and executes the model, such as Ollama; it is not a Coding Agent.
- Coding Agent: An assistant that reads files, edits them, runs commands, and checks the result, such as Claude Code, OpenCode, Pi, or Aider.
⏱️ Expand: time, environment and safety bottom line
- Each recipe takes about 20–50 minutes; complete the shortest path first, then do the advanced options.
- Git, Python 3.11+, and Node.js 20+ are useful here. Install only what your chosen recipe needs.
- Practice using test materials only. Don't paste passwords, API keys, unpublished papers, or private files into tools you don't trust.
- Before an action deletes, sends, publishes, or changes many files, inspect its diff or preview.
1. Write your first Skill¶
Result: Create one reusable instruction card for your project and run it once.
First create a folder:
mkdir -p .claude/skills/summarize-changes
Expand complete steps, tests and FAQ
Create .claude/skills/summarize-changes/SKILL.md:
---
description: Summarize uncommitted changes and flag risks. Use when the user asks what changed or requests a diff review.
---
## Instructions
1. Read the current git diff.
2. Explain the change in three short bullets.
3. List risks, missing tests, and files that should not be committed.
4. If there is no diff, say so. Do not invent changes.
After starting Claude Code, enter:
/summarize-changes
You can also ask, "What did I just change?" Claude should choose the Skill automatically. It normally notices changes to SKILL.md inside an existing skills directory without a restart. Restart only if .claude/skills/ did not exist when the session began.
Success criteria: The answer is really based on the current diff, and it says "what could go wrong".
FAQ:
| Symptom | What to check first |
|---|---|
/summarize-changes does not exist |
Check that the path is exactly .claude/skills/summarize-changes/SKILL.md |
| It triggers for unrelated requests | Make the "when to use" sentence in description more specific |
| The Skill is becoming too long | Move background material into a reference file in the same folder and read it only when needed |
Start with a project Skill because it travels only with this repository. Move it to the personal path ~/.claude/skills/<name>/SKILL.md only after you know several projects need the same procedure.
| Often-confused item | What it solves | When to use it |
|---|---|---|
| One-off Prompt | Describes only the task in front of you | The procedure will not be reused |
| Skill | Saves how to handle a recurring kind of work | The same procedure recurs in a project |
| MCP Server | Provides a new typed tool, data source, or service | The Agent must call an external program or API |
A Skill can direct an Agent to use existing tools, but a Skill is not a new API. Do not use the oversimplification that “Skills cannot read files while MCP can” to distinguish them.
If you want to do a formal eval, you can test the description with a fixed "should trigger/should not trigger" sentence, and then check whether the answer follows the four steps.
2. Write your first MCP server¶
Result: Create an MCP tool that adds two numbers and make it visible to Claude Code.
First install the currently stable MCP SDK in a clean Python environment:
python -m pip install "mcp>=2,<3"
Expand the server program, connection methods and error troubleshooting
Create server.py:
from mcp.server import MCPServer
mcp = MCPServer("hello-mcp")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
if __name__ == "__main__":
mcp.run()
This program is short because MCP v2 creates an input schema from type hints, uses the docstring as the tool description, and wraps return values as MCP content. Incorrect parameter names, types, or docstrings can make an Agent choose the wrong tool or pass the wrong data.
Add this local stdio server to Claude Code:
claude mcp add --transport stdio hello-mcp -- python server.py
claude mcp get hello-mcp
Enter Claude Code and ask: "Use add to calculate 27 + 15." If successful, you should get 42, and you can see the parameters in the tool call record.
The high-level class in MCP v2 is MCPServer, imported with from mcp.server import MCPServer. Do not mix this example with old FastMCP tutorials or v1 import paths.
Safety bottom line:
- Give a tool only the parameters it needs.
- Limit file tools to the directories they need to read or write.
- Require human approval before writing, paying, sending, or deleting.
- A third-party MCP server may see your data. Check its source and permissions before installing it.
| Transport | Best for | Verification note |
|---|---|---|
| stdio | Claude Code or a desktop host on the same computer | Use this for a first server; OAuth is usually not implemented inside the transport |
| Streamable HTTP | Remote, multi-user, or service deployments | Design authentication against the current MCP authorization specification; do not copy old HTTP+SSE tutorials |
When you need an API key, read it from an environment variable. Do not put a secret in server.py, a configuration example, or Git.
If claude mcp get shows failure, first run python server.py directly to see the import error, and then confirm that the startup command after -- is consistent with the Python environment.
3. Office Docs Workflow¶
Result: Generate a file from test data, then inspect it in a real Office app or PDF reader.
First download Anthropic's official reference repository:
git clone --depth 1 https://github.com/anthropics/skills.git anthropic-skills-reference
Expand skill installation, sample prompt and quality check
The docx, xlsx, pptx, and pdf folders in anthropics/skills are complex Skill references used in Anthropic products. They are source-available, not Apache-2.0 open-source examples. Read each folder's license and SKILL.md first.
To try out a skill within a project, place the skill itself at the correct level, rather than wrapping the entire repo in an extra layer:
mkdir -p .claude/skills
cp -R anthropic-skills-reference/skills/docx .claude/skills/docx
PowerShell can be used instead:
New-Item -ItemType Directory -Force .claude/skills
Copy-Item -Recurse anthropic-skills-reference/skills/docx .claude/skills/docx
The four folders are not interchangeable. Install only the one you want to practice first:
| Skill | First small task | Check when finished |
|---|---|---|
docx |
Make a one-page summary from test data | Title, paragraphs, tables, and page breaks |
xlsx |
Total a small table while preserving formulas | Formulas, cell types, and values |
pptx |
Make three slides from a three-point outline | No overflowing text; images and sources are correct |
pdf |
Extract three claims from a public PDF | Page numbers, citations, and source text match |
Copyable DOCX task:
Create a one-page DOCX summary from the test data I provided.
Keep a title, three key points, and a source field. Write "missing" when the data is absent; do not guess.
Reopen the finished file and check for clipped text, blank pages, and broken tables.
Check in this order: content → formulas and numbers → layout → whether the file reopens. A message saying "file created" is not proof that the file is correct.
If the skill does not appear, make sure the path is .claude/skills/docx/SKILL.md. The file capabilities built into Claude's product may differ from the reference version you clone, so don't claim that the two will necessarily produce exactly the same results.
4. Gemini Notebook Workflow¶
Result: Add your own sources and get cited answers you can check against the originals.
Google renamed NotebookLM to Gemini Notebook; some packages and URLs still use the old name. Start with the official website:
python -m webbrowser https://notebooklm.google.com
Upload two public documents and ask: "Where do these sources agree and disagree? Cite a source for each point." Open every citation and compare it with the original before you automate anything.
Expand the community CLI automation path: notebooklm-py
Google does not currently provide a public official API for this automation. notebooklm-py is a community project that uses an unpublished interface. It is useful for personal research and prototypes, but a production workflow needs a fallback in case it breaks.
uv tool install "notebooklm-py[browser]"
notebooklm login
notebooklm auth check --test --json
notebooklm create "My Research"
notebooklm use NOTEBOOK_ID
notebooklm source add ./paper.pdf
notebooklm ask "List three main claims and cite a source for each one."
To make Claude Code or other tools that support Agent Skills use it:
notebooklm skill install
Signing in will open the browser and save the verification status. Don't commit cookies, tokens, or personal browser data to Git.
Expand another browser skill and troubleshooting reminder
PleasePrompto/notebooklm-skill is archived (checked 2026-09-10 UTC), with no further updates or support. It demonstrates a historical browser-based notebook query approach, not an official Google integration. For new workflows, use the official website or separately assess notebooklm-py above.
How to choose:
| What you need | Best starting point |
|---|---|
| Just want reliable reading and manual verification | Gemini Notebook official website |
| Want to add sources, Q&A or export in batches | notebooklm-py CLI |
| Study early browser-based Skill design | notebooklm-skill (archived; historical reference only) |
If your login fails, first go back to the official website to confirm that your account can be used normally, and then log in again according to the community project's own auth instructions. Don't use lots of retries to bypass Google's restrictions.
5. Zotero Workflow¶
Result: Find an item through Zotero's local API. Before writing anything, preview and approve the change.
In Zotero, enable "Settings → Advanced → Allow other applications on this computer to communicate with Zotero," then test the local API:
curl http://localhost:23119/api/
Expand search, Zotero 10+ write authorization and security practices
The local API lives at http://localhost:23119/api/. It works offline and is not subject to the Web API rate limit. Zotero 10+ supports POST, PUT, PATCH, and DELETE, so old read-only guidance is no longer correct.
Write access is not enabled silently. An app must request a local API key from /api/local/authorize, and Zotero shows an approval window. This key is different from a zotero.org Web API key and can change any library you are allowed to edit, so:
- Only read and search for the first time.
- List the items expected to be added, moved or deleted before writing.
- Let the user approve in the Zotero window.
- After practicing, go to Settings → Advanced and press Clear Write Authorizations to cancel the remembered key.
When using WenyuChiou/zotero-skills, you can copy this sentence first:
Search only; do not change anything. Find Zotero items published after 2024 about multi-agent evaluation.
List each title, year, DOI, and Zotero item key. Write "not provided" for a missing field.
Only try writing for the second time, and ask for preview first:
Prepare to add those results to the "agent-evals" collection.
List the item keys that would move, but do not make the change. Wait for my approval before writing.
403 usually means that the native API is not enabled; 401 means that the write key does not exist or is invalid; 428 means that the write lacks the correct Zotero-Server-ID.
6. Local LLM + CLI Agent quick walkthrough¶
Result: Let a Coding Agent use a model on your computer to make one small change that Git can undo.
First install Ollama and download the current lightweight model:
ollama pull gemma4:e4b
Let’s first distinguish what they are:
| Name | What it does | What it is not |
|---|---|---|
| Ollama | Loads and runs a model on your computer | It does not read a repo, edit files, or run tests by itself |
| OpenRouter | Routes one API account to many cloud models and providers | It is not a local model or a terminal Coding Agent |
| OpenCode／Pi／Aider | Coding Agents that read files, edit them, and run commands | They are not models; each still needs a local or cloud model |
| Claude Code | A Coding Agent built for Claude | Its official setup cannot replace Claude with an Ollama model |
Expand the main path: OpenCode＋Ollama
OpenCode is the Coding Agent that reads files, edits them, and runs commands; Ollama is the runtime that runs a model locally. Install OpenCode, then start it with opencode:
curl -fsSL https://opencode.ai/install | bash
opencode
OpenCode automatically looks for Ollama at http://127.0.0.1:11434. In the TUI, select ollama/gemma4:e4b, open a practice repo already managed by Git, and paste:
Change only README.md by adding one line: "Local agent test".
First tell me where you will edit. After editing, show the diff and do not commit.
Success criteria: only README has been modified, diff meets the requirements, and there are no unfamiliar files in git status. When the model is small, the task should also be small; only change one thing at a time.
Expand the Aider alternative, Pi／OpenRouter options, and troubleshooting
Aider officially recommends using aider-install, and Ollama model prefix uses ollama_chat/:
python -m pip install aider-install
aider-install
aider --model ollama_chat/gemma4:e4b
Other options:
- Pi is an extensible Agent harness and Coding Agent. It inherits the user's permissions by default, so use a separate sandbox or container for sensitive projects.
- OpenRouter provides one API for many cloud models and providers. It may cost money, and data handling depends on the provider you select.
- The Complete CLI Agent Guide explains when to choose Claude Code, OpenCode, Pi, Aider, OpenRouter, or a local runtime.
FAQ:
| Symptoms | What to do first |
|---|---|
| Ollama model not found | Run ollama list and make sure the tag is exactly gemma4:e4b |
| Slow answer or out of memory | Use gemma4:e2b instead and narrow the task and context |
| Agent changed too many files | Stop immediately and inspect git diff; shrink the task to one change in one file |
| Tool calling is unstable | Use a Stage 3 model that officially supports tool calling |
📚 Required reading¶
These are the fact sources for the instructions above. You do not need to read them all: start with the row for your chosen recipe.
Data verification: 2026-08-30 UTC
| Source | What to see first | Editor's Rating |
|---|---|---|
| Claude Code — Skills | Path, triggering method and live change detection | ⭐⭐⭐⭐⭐ |
| MCP Python SDK v2 — What’s new | Differences between MCPServer import and v1→v2 |
⭐⭐⭐⭐⭐ |
| Anthropic Skills | Skill structure and file skill authorization | ⭐⭐⭐⭐⭐ |
| Google — NotebookLM is now Gemini Notebook | The new product name and what remains available | ⭐⭐⭐⭐⭐ |
| Zotero Local API | Local API, write authorization, and revocation | ⭐⭐⭐⭐⭐ |
| OpenCode | Installation, the opencode command, and local model connection |
⭐⭐⭐⭐⭐ |
| Aider＋Ollama | Correct installation with ollama_chat/ prefix |
⭐⭐⭐⭐⭐ |
| Ollama — Gemma 4 | e2b/e4b tag and hardware selection |
⭐⭐⭐⭐⭐ |
⭐ Curated projects and learning resources¶
The rating measures teaching usefulness in this project. It is not a GitHub star count or a permanent score.
| Category | Project／resource | Use it to | Limitation | Rating |
|---|---|---|---|---|
| Skills | Agent Skills standard | Understand the skill format shared across tools | Each product still has its own expansion field | ⭐⭐⭐⭐⭐ |
| anthropics/skills | Read mature skill examples | File skills are source-available | ⭐⭐⭐⭐⭐ | |
| MCP | MCP specification | Check the formal definition of protocol | You don’t have to read it from the beginning to get started | ⭐⭐⭐⭐⭐ |
| MCP Python SDK | Use Python to write server/client | Note that v1 and v2 teaching cannot be mixed | ⭐⭐⭐⭐⭐ | |
| Documents | Anthropic DOCX skill | Study a complex document Skill | Check its license and runtime requirements first | ⭐⭐⭐⭐ |
| Anthropic XLSX skill | Learn spreadsheet analysis and output process | Finished products still need to be checked with spreadsheet software | ⭐⭐⭐⭐ | |
| Gemini Notebook | notebooklm-py | Add sources, ask questions, and export artifacts in batches | Unofficial; its unpublished API may change | ⭐⭐⭐⭐ |
| notebooklm-skill | Study early browser-based Skill design | Archived; unofficial, historical reference only | ⭐⭐⭐ | |
| Zotero | zotero-skills | Search and organize Zotero from an Agent | Always preview before writing | ⭐⭐⭐⭐ |
| research-hub | Connect Zotero, Obsidian, and a research workflow | More advanced than a single recipe | ⭐⭐⭐⭐ | |
| zotero-gpt | Chat while reading inside Zotero | A Zotero plugin follows a different path from an external Agent | ⭐⭐⭐ | |
| Local/CLI | OpenCode | Change programs with local or cloud models | Check provider and permission settings first | ⭐⭐⭐⭐ |
| Pi | Extensible coding harness/CLI | No built-in permission isolation by default | ⭐⭐⭐⭐ | |
| Aider | Pair-program with a Git-centered workflow | Small local models may not code well enough | ⭐⭐⭐⭐ |
✅ Completion check and next stop¶
- I have completed at least one recipe and can point out the generated file, tool or answer.
- I've seen the success path and I've seen a failure message or error output.
- I did not submit tokens, cookies, personal files or unpublished information.
- I know whether I'm using the official feature or Community Integration.
- Any write or bulk changes have preview, diff or manual approval.
Then return to Stage 5 to choose the next skill. To find more tools, open the MCP／Skills Catalog.