Addy Osmani 讲解如何上手 Claude Code Mods
Core Highlights
Google engineering lead Addy Osmani published a guide on getting started with Claude Code Mods — a modular mechanism for customizing and extending how Claude Code behaves.
What Mods Are
In plain terms, Mods are a way to install "plug-ins" into Claude Code: you prepare frequently used instructions, constraints and workflows in advance, load them on demand, and make the coding agent behave in ways that fit a particular project, without rewriting the prompt every time. Osmani's guide walks through the onboarding path: initializing a mod, defining what it should do, and invoking it inside a session. The value lies in turning scattered "project rules" into reusable assets, so a new team member can acquire the defaults of a veteran with a single command.
Technical Details
Mods sit alongside agent skills and MCP in the same ecosystem, and the three are complementary: skills teach the model how to do something, MCP connects the model to external tools, while Mods look more like session-level preset personas and workflows. The concrete implementation defers to official documentation, and Osmani's treatment is intentionally introductory — focused on first steps and best practices rather than internals. Compared with writing rules into CLAUDE.md or a system prompt, Mods have finer granularity and can be switched by scenario. They resemble GitHub Copilot's agent skills in spirit but put more weight on modular composition within a session.
Comparison and Use Cases
For teams, Mods represent a step toward turning "coding conventions" from documents into executable default behavior, cutting the context-switching cost of running an agent across multiple projects. The intelligence station recommends following official documentation when adopting them.
Further Context
The appeal of Mods is easiest to appreciate by considering how agents actually fail in real repositories. A model that performs brilliantly on a generic benchmark can still produce code that violates a team's naming scheme, ignores an internal testing convention, or reaches for a dependency the company has banned. Those are not reasoning failures; they are context failures. A well-designed mod encodes exactly that local knowledge — the unwritten rules that experienced engineers carry in their heads — and applies it consistently at the moment the agent writes code. That is why the modular, switchable format matters: a single monolithic system prompt cannot elegantly serve a monorepo that contains a legacy service, a modern API and a data pipeline, each with its own conventions.
There is also a collaboration dimension. When Mods are checked into a repository alongside the code, they become part of the team's shared source of truth. Code review can cover the agent's operating rules just as it covers application logic, and updates propagate to everyone at once. This is a meaningful improvement over the common pattern in which each engineer maintains a private, drifting collection of prompt snippets.
Practitioners should keep a few cautions in mind. Mods that grow too broad begin to resemble the very monolithic prompts they were meant to replace, so keeping them focused is important. Because behavior is defined in configuration that the agent reads, changes should be tested against representative tasks before rolling out to an entire team. And since the wider ecosystem — skills, MCP, Mods — is still evolving, pinning to documented, stable interfaces will avoid surprises. Used with that discipline, Mods are a practical way to make an agent feel less like a generic assistant and more like a properly onboarded teammate.
Additional Notes
A practical question that comes up quickly is how Mods differ from simply maintaining a long CLAUDE.md file. The answer is scope and composability. A repository-level instruction file is always on and applies uniformly, which is useful for rules that truly are universal. A Mod is loaded for a specific purpose — a migration task, a code review pass, a particular client's conventions — and can be combined with others. That makes it possible to keep a small set of orthogonal building blocks rather than one sprawling document whose sections increasingly contradict one another. Teams that manage several projects often find this the cleaner mental model.
There is a learning curve worth acknowledging. Writing an effective Mod requires understanding both the task and the way the agent interprets instructions, and a poorly specified Mod can be worse than none — confidently steering the agent in the wrong direction. Osmani's beginner-oriented framing is therefore appropriate: start with one narrow, well-understood behavior, verify it works, and expand gradually. Treat Mods as code, with review and version control, rather than as disposable notes.
Looking ahead, the direction is toward richer composition between Mods, skills and MCP tools. An agent might load a skill for domain knowledge, a Mod for house style, and MCP connectors for external systems, with each layer handling a distinct concern. That separation of responsibilities is healthy architecture, and it is why the topic draws attention beyond a single tool's user base.