What Are Agent Mods (and Should You Use Them)?

Quick answer
A mod packages several customisations into one installable unit, typically instructions, reusable commands, and behaviour hooks.
Claude Code introduced mods in October 2026; other harnesses ship equivalent bundles under different names.
Mods differ from skills: a skill is a procedure loaded on demand, while a mod changes the harness itself.
Because a mod can change behaviour globally, it deserves a stricter review than a skill.
Use a mod when you want a consistent setup across projects, and a project-level file when only one repository needs it.

What is an agent mod?

A mod is a bundle that customises how an agent works. Instead of copying a set of files into each project, you install one package that can carry instructions, commands, hooks, and presentation changes. The exact surface depends on the harness, so the vendor documentation is the authority on what a mod may touch.

The distinction from a skill matters. A skill is content the agent may load for one task. A mod changes the environment the agent runs in, which is closer to installing software than to writing a document.

Why would you install one?

Consistency. A team that works across several repositories can ship one mod with the conventions, commands, and guardrails it wants everywhere, instead of maintaining a copy in each project. That is the same argument as a shared linter config, with the same trade-offs.

Convenience is real but so is the cost: a mod that changes behaviour globally affects repositories whose owners never agreed to it. Install mods at the scope where the agreement exists.

How do you evaluate a mod before installing it?

Read what it installs. Look for hooks that run commands, instructions that override safety behaviour, and anything that adds credentials or network access. A mod that says it “improves workflow” but contains a shell hook is a program, not a preference.

Then check the scope. Prefer project-level installation for anything that changes how code is written, and user-level only for presentation and personal ergonomics. If the mod is distributed as a moving target rather than a pinned version, treat it as unreviewed on every run.

# Inspect a mod bundle before installing it
find ./mod-name -type f | sort
grep -RInE 'hook|exec|spawn|curl|wget|token|secret|\.env' ./mod-name | head -40
# Install only from a pinned version you reviewed

What can go wrong?

The main risk is silent global change. A mod can alter instructions in every session, and the effect looks like the model behaving differently rather than like a package you installed. When behaviour changes across unrelated projects, the installed mods are a place to look.

The second risk is composition. Two mods that each adjust instructions can conflict, and the resulting behaviour is neither one. Keep the set small, and remove anything you cannot explain.

Where this bites vibecoders
An AI assistant will recommend a mod by describing what it promises, not what it installs. Ask for the file list and the hooks before you run the install command, and do not accept “it just improves the workflow” as a description of a package that can execute code.

Where AI coding assistants get this wrong

Installing a mod globally for a task that one project needed.
Skipping the hook and command review because the mod is popular.
Assuming a mod is equivalent to a skill and reviewing it as text only.
Running several mods that override the same behaviour.
Following an unpinned install command from a generated answer.
Forgetting which mods are installed when debugging odd agent behaviour.

Checklist

List the files and hooks the mod installs.
Read anything that executes a command.
Install at project scope unless it is purely personal.
Pin the version and review updates.
Keep the installed set small enough to explain.
Record installed mods in the repository documentation.

FAQ

Are mods the same as plugins?

They occupy the same role: a packaged extension to the agent’s behaviour. Different harnesses use different names and allow different capabilities. Check what the specific product permits before assuming a plugin from one tool works in another.

Do mods replace AGENTS.md?

No. AGENTS.md is project documentation that travels with the repository. A mod is installed into the harness and can apply to many projects. Rules that only make sense for one repository belong in that repository’s AGENTS.md.

Can a mod read my files?

It can include instructions or hooks that cause the agent to read files, and a hook may run with your user permissions. That is why the review is about capabilities, not claims. If you cannot tell what it executes, do not install it.

How do I remove one cleanly?

Uninstall it through the same mechanism you used to install it, then verify that the instructions and hooks it added are gone. Check a fresh session in a repository that was affected, because a leftover instruction file is easy to miss.