A Mental Model for Claude Code: Skills, Subagents, and Plugins

TL;DR

Three teams, three AI tools, no shared output to compare. We consolidated to Claude Teams to fix that.
Claude Code's extension system has three parts: knowledge (CLAUDE.md + Skills), workers (Subagents), and packaging (Plugins).
CLAUDE.md is always-on context. Skills load on demand. If you mix this up, you're burning context on things Claude doesn't need in 90% of sessions.
Context degradation is real: mid-migration, Claude started contradicting decisions from 20 messages back. Not an error. It just lost the thread.
We're building a security reviewer, dependency auditor, and migration checker as Subagents, plus a shared conventions Plugin. Not shipped yet. Follow-up post coming with numbers.

We're 150 people. D2C storefronts on Medusa and Shopify, cloud migrations to AWS, AI products for brands, marketing automation. TypeScript, Next.js, Postgres throughout. Not a research lab. We ship production code for real clients.

When Claude Code launched, the team picked it up fast. But "using Claude Code" meant something different depending on who you asked, and nobody had thought to align on that.

The tool fragmentation problem

Our D2C team was deep in Cursor. Cloud team on Claude.ai. A few engineers on ChatGPT. Same tasks, three different tools, and nobody could tell which approach was actually working better because the outputs weren't comparable. You can't build shared tooling on top of three different surfaces. You can't even have a useful conversation about what's working.

We moved everyone to Claude Teams. Once we were on a single baseline, the next problem showed up: when engineers talked about extending Claude Code, they meant different things. "Just add it to Claude" was CLAUDE.md to one person, a slash command to another, and a custom agent to a third. The terminology wasn't shared, so the work wasn't either.

Getting clear on the architecture fixed that. Here's the model we use now.

Knowledge, workers, packaging

Everything in Claude Code's extension system is one of three things.

Knowledge is what Claude knows about your project, loaded into context so Claude can work within your conventions without you re-establishing them every session.

Workers are isolated Claude instances that handle heavy tasks outside your main session. They run, return the result, and don't leave their working memory behind in your context.

Packaging is how you make knowledge and workers portable and shareable across repos, teams, client engagements.

That's CLAUDE.md and Skills, Subagents, and Plugins.

CLAUDE.md and Skills

CLAUDE.md

CLAUDE.md sits at the root of your project. Claude reads it at the start of every session and it stays in context the whole time. Whatever's in there, Claude just knows.

We keep CLAUDE.md files at two levels: project-level and user-level at ~/.claude/CLAUDE.md. Our project files hold the rules that apply to nearly every task in that codebase:

"This is a Medusa v2 project. Use @medusajs/framework imports, not v1 patterns."
"Never write raw SQL. Use the Medusa service layer or MikroORM repositories."
"All API responses follow our envelope pattern: { data, meta, error }."
"Default AWS region is ap-southeast-1."

The thing to understand about CLAUDE.md is that it's always consuming your context window. Every session, start to finish. If a rule only applies in specific situations like a PR review, a scaffolding task, or a migration, it doesn't belong here. That's what Skills are for.

Skills

A Skill is a folder with a SKILL.md file. Claude loads it when the situation calls for it, not every session.

We've built Skills for:

Medusa module scaffolding: naming conventions, folder structure, how services wire into the container. An engineer asks Claude to create a new module and it already knows how we do it.
AWS CDK standards: specific patterns for VPCs, Lambda functions, RDS clusters. The conventions we follow on every project.
PR review protocol: a checklist before any PR goes up. Doesn't need to be in CLAUDE.md: you're not reviewing PRs every session.
Architecture diagrams: a consistent Mermaid format across services. One skill, every team.

Claude discovers Skills through their description field. This is doing more work than most people realise:

description: Use when creating a new Medusa module, service, or repository file

vs.

description: Helps with backend code

The first one will get triggered at the right moment. The second is basically useless.

One thing worth knowing: disable-model-invocation: true prevents Claude from auto-triggering a skill. We use it for anything with side effects: deployments, migrations, seed scripts. You want those called explicitly.

Subagents

Here's the problem that pushed us toward Subagents.

We were writing migration scripts for a legacy e-commerce backend moving to Medusa v2. The codebase was 200+ files. As the migration got complex, the session kept accumulating: file reads, schema traces, analysis, conversation history. At some point Claude started writing code that contradicted decisions made earlier in the same session. Syntactically correct. Wrong. It hadn't thrown an error. It had just lost track of what we'd established.

You feel it before you can name it. Claude re-explains a constraint you already covered, or generates something that quietly ignores an assumption from 15 messages back. That's when you know the session has gotten too heavy.

A Subagent runs in its own context window. It does the research or the heavy work, hands back the result, and your main session never sees the noise. Just the answer.

Claude Code already ships with built-in subagents most teams never consciously use: an Explore agent for read-only research, a Plan agent that runs during planning mode, a documentation agent for reference lookups. The pattern is already baked in.

We're building custom ones:

A security reviewer that runs on every backend PR: exposed credentials, unsafe queries, missing auth middleware
A dependency auditor that scans package.json across our monorepo and flags version inconsistencies
A migration sanity checker that reads a Postgres migration file and confirms it's reversible before it runs

None of these are in production yet. They should be within the week. I'll write a follow-up with actual numbers once they're running.

One pattern worth wiring up now: you can load specific Skills directly into a Subagent's context at startup:

---
name: medusa-api-developer
description: Implement Medusa API endpoints following Devx conventions
skills:
  - medusa-module
  - api-envelope-pattern
---

Implement API endpoints. Follow the conventions from the preloaded skills.

The subagent doesn't discover those skills at runtime. They're already there. You guarantee the specialist knows your standards.

There's also context: fork for running a Skill in an isolated context, which keeps your main session clean during research-heavy work. Useful if you want the output but not the context cost.

Plugins

Once you've built Skills and Subagents, Plugins are how you stop copying files between repos.

We have four service lines: Shopify, Medusa, AWS infrastructure, AI products. Right now, convention files live per-repo. Every new Medusa project starts with a manual copy step. It's already annoying.

The plan is one conventions plugin per service line:

devx-medusa-conventions/
  .claude-plugin/
    plugin.json
  skills/
    medusa-module/
      SKILL.md
    api-envelope-pattern/
      SKILL.md
    pr-review/
      SKILL.md
  agents/
    security-reviewer.md
    migration-checker.md

Install it once, and any engineer on any Medusa project gets the shared conventions. We're building this out now. Not shipped, but the structure is laid.

For client work, the same pattern applies. Each engagement gets a plugin with that client's tech stack and conventions. You stop re-establishing context every session.

What still requires good engineers

There's a version of this story where the takeaway is "Claude does the engineering work now." I don't think that's right, and Claude Code's architecture makes that clear.

The engineers at devx who get the most out of Claude Code have done the work of building the knowledge layer, codifying Medusa module patterns, AWS CDK conventions, API standards into CLAUDE.md files and Skills. They know when a task is about to overload a session and spin up a subagent before the context degrades.

That judgment doesn't come from the tool. Claude doesn't write its own CLAUDE.md. An engineer who understands both the system and the codebase does.