The Copy-Paste Agent¶

Duplicating agent definitions across projects instead of composing from shared skills causes independent drift and prevents improvements from propagating.

What it looks like¶

You build a useful agent for one project, then copy it to a second. After a few projects, 5 slightly different versions exist. Each one has been tuned locally. When you improve the original, the copies do not benefit.

The symptom is the same agent definition — same core instructions, same tool list, same behavior — appearing in multiple repositories with small variations (the pattern replication risk made concrete). The variations are rarely intentional. They accumulate through local fixes that never make it back to a shared source.

Why it happens¶

The immediate cause is the absence of a sharing mechanism. When copying a file is faster than setting up a skill or plugin, copying wins. The second cause is awareness: many teams do not realize that Claude Code supports user-level agents at ~/.claude/agents/ and project-level skills that they can compose rather than duplicate.

The fix¶

Extract the shared parts of an agent definition into a skill — the separation of knowledge and execution applied to agents. Skills are the reusable unit — they live in one place, and agents compose them. When the skill changes, all agents that reference it get the update automatically.

For cross-project sharing, package skills and agents as plugins and install them across projects. For personal reuse across all projects, place agents and skills in ~/.claude/agents/ and ~/.claude/skills/ — they are available to any project session (Skills documentation).

The anti-pattern within the anti-pattern¶

Copying a skill file instead of referencing it recreates the original problem at a lower level. The skill becomes duplicated across agents, and the duplication still drifts.

Key Takeaways¶

Copied agent definitions drift independently — improvements to one copy don't propagate.
Extract shared knowledge into skills; compose agents from skills rather than duplicating definitions.
User-level and plugin-level sharing mechanisms exist — use them before reaching for copy-paste.

Example¶

A team builds a code-review agent for their backend repository. Its .claude/agents/code-review.md contains instructions for checking type safety, test coverage, and security patterns. The agent works well, so it gets copied into the frontend and mobile repositories.

Six months later:

The backend copy — code-review.md — has been updated to enforce a new API naming convention.
The frontend copy has been tuned to flag React anti-patterns.
The mobile copy has been modified to skip certain checks that don't apply to native code.

When a new security rule is discovered and added to the backend copy, the frontend and mobile copies never receive it.

Fixed with skills: extract the shared rules into ~/.claude/skills/security-review/SKILL.md. Each repository's agent references it via the skills: frontmatter field (for example, skills: [security-review]). When the skill is updated, all three agents benefit automatically. Repository-specific rules remain in each agent definition without duplicating the shared core.

When this backfires¶

Extracting shared skills only helps when you maintain agents over time. 3 conditions make the anti-pattern less harmful than it appears:

True one-off agents: an agent built for a single short project that will never be reused or updated does not accumulate drift — copies never diverge because changes never happen.
Premature abstraction cost: extracting a skill before the shared core stabilizes forces every downstream agent to absorb every experimental change. Waiting until the shared behavior is settled reduces churn.
Transient fork intentionality: occasionally a copy is an intentional fork — one project needs behavior that diverges fundamentally. In this case the copies are meant to diverge, and a shared skill adds coupling without benefit.

The pattern is harmful specifically when agents are expected to receive updates and improvements. If none of these 3 conditions hold, audit whether the shared skill is pulling its weight.