Fundamentals of Claude Cowork Skill Architecture

The most useful mental model for writing Claude Cowork instruction files is one most product managers already own. Claude Cowork is a brand-new employee on their first day. It knows nothing about your company, your clients, your tools, your naming conventions, or your definition of good work. Every piece of context you would give a human hire, you have to teach Claude explicitly, in writing — identity, workflow, naming rules, expected outputs, all spelled out. CLAUDE.md and SKILL.md are how you write that curriculum down. They are the guardrails that define where the agent can operate and how it must behave inside them. Claude Cowork skill architecture, underneath the technical vocabulary, is the architecture of an onboarding playbook.

The lesson that reshapes everything else is that the instructions split into two layers, not one. A single file cannot do the job. Cram everything into one CLAUDE.md and the file becomes the handbook no employee actually reads. Split the guidance into a short generalist file plus a set of focused specialist files, and the agent starts behaving like a careful senior team member rather than a confused new hire on their first week.

This post walks through the two-layer model. What belongs in CLAUDE.md. What belongs in SKILL.md. How Cowork's progressive-disclosure loading behavior reshapes the way specialists should be written. How skills coordinate through cross-references. And how user requests actually match to the skills that execute them.

None of this is theoretical. Every rule in this post comes from a CLAUDE.md or SKILL.md file that was rewritten three, four, or five times until the agent started producing output that looked like a senior employee rather than a new hire.

01 The Two-Layer Model

Claude Cowork exposes two primary instruction mechanisms. Each one has a different job. Most of the early pain comes from confusing the two.

CLAUDE.md is the generalist layer. One file at the top of the stack — user-level or project-level. The agent has access to it in every session. Everything in it applies universally — identity, session workflow, file-naming conventions, output destinations, collaboration rules, date formats, platform-specific path handling. If a rule should apply whether the agent is writing a blog post, drafting a proposal, or debugging a spreadsheet, it belongs here.

SKILL.md is the specialist layer. Many files, one per discipline. Claude loads a specific SKILL.md when the agent matches the user's request against the skill's description and decides the skill is relevant to the current task. Everything inside a SKILL.md is domain-specific: brand voice rules, accessibility audit checklists, proposal templates, SEO briefs, PRD formats. Each gets its own file.

The same skill system runs under Claude Code and the Agent SDK — the architecture patterns that follow apply everywhere Claude loads skills, though the trigger behavior is most visible inside Cowork.

The split matters because large language models have a context budget, and new employees have attention budgets. A handbook that lists every rule for every department is something a new hire skims, not reads. A short orientation document plus a role-specific playbook is something a new hire actually uses.

The practical consequence: when the generalist layer stays short and the specialists stay focused, the agent's output becomes measurably more consistent. When the generalist layer bloats, consistency degrades — and the degradation is not subtle after the file crosses a few hundred lines of mixed content.

02 What Belongs in CLAUDE.md

The generalist layer answers one question: regardless of what you are doing right now, how should you operate?

Five categories belong in CLAUDE.md, in roughly this order of importance:

1. Identity         — name, company, role, contact details
2. Session workflow — /standup at start, /conclude at end, plan-before-execute
3. Collaboration    — never overwrite without confirmation, ask when ambiguous
4. Output           — date format, currency, timezone, path separator
5. Naming           — folder structure, file naming, path length limits

A few lines each. Every rule applies to every task, on every session, without exception.

What does NOT belong in CLAUDE.md:

• Brand voice rules — specialist, goes in a brand-voice SKILL.md
• Accessibility standards — specialist, goes in an accessibility SKILL.md
• Proposal templates — specialist, goes in a proposal SKILL.md
• Blog formatting — specialist, goes in a blog-writer SKILL.md

A useful test: if a rule only applies to some tasks, it belongs in a SKILL.md. If a rule applies to every task, it belongs in CLAUDE.md. Anything borderline should default to a SKILL.md. The cost of over-loading the generalist layer is paid on every session, forever, because the agent carries it in context whether the current task needs it or not.

Put this through the new-employee frame: the generalist rules are the things you tell a new hire on day one, before they know what role they will be in. The specialist rules are the things you tell them once they sit down at their desk and open their first task.

03 What Belongs in SKILL.md — Four Examples

The specialist layer answers a different question: when a user asks for this specific kind of work, what rules and references should be active?

Four concrete SKILL.md examples show the shape.

Accessibility. Full WCAG 2.2 AA standards. Contrast ratios, keyboard navigation patterns, focus management rules, touch target sizes, ARIA usage. This skill applies when the agent is producing or reviewing any web or app deliverable. It does not apply when the agent is drafting a cold email.

UI/UX Design. Hierarchy and clarity principles, consistency rules, jobs-to-be-done framing, conversion principles, adoption heuristics, dropoff reduction patterns. Applies when the agent is designing a user flow, reviewing a mockup, or writing a product specification.

Product Documentation. PRD structure — problem, users, goals, non-goals, user stories, functional requirements, non-functional requirements, data model, integrations, milestones, metrics. Applies when the user asks for a spec, an MVP scope, or a product brief.

Technical Architecture. Framework selection between WordPress, Shopify, and Next.js. Directory structure standards, template patterns, Server vs Client component rules, security hardening, performance targets. Applies when the agent needs to decide or document framework architecture for a build.

Each of these skills is focused on one job. None duplicate rules from another. None include rules that belong in CLAUDE.md. Each is written to be loaded only when its description matches the user's intent.

The internal shape of a SKILL.md is consistent across all four:

---
name: skill-slug
description: "What it does + trigger phrases"
---

# Skill Title

One-sentence purpose statement.

**Depends on:** generalist brand skill
**Also loads:** peer specialist skills this one references

## Rules (grouped by sub-topic, never nested deeper than ###)
## Examples (Good and Bad pairs where ambiguous)
## QA checklist (run before declaring the work done)

When the shape is consistent, the agent knows where to look for what, regardless of which specialist it is running. A standardized role playbook is easier to read on day one than a bespoke one for every department.

04 Progressive Disclosure: Only SKILL.md Auto-Loads

Here is the finding that reshapes how a well-architected skill stack should be written: Cowork uses progressive disclosure to manage skill content. When a skill triggers, only the top-level SKILL.md is auto-loaded into the agent's context. Supporting files in the skill folder — reference documents, scripts, templates, examples — are not auto-loaded. They load on demand, when the SKILL.md instructs the agent to read a specific file via the Read tool or run a script via Bash.

This is not a limitation. It is how the system preserves context budget.

A SKILL.md that tries to include everything — all the accessibility standards, every worked example, every edge case — consumes the agent's attention budget on content the current task may not even need. A SKILL.md that stays lean and references longer material on demand uses the budget only for rules that are active right now.

The practical shape looks like this:

skills/
  my-skill/
    SKILL.md                 ← lean; rules the agent must always follow
    references/long-ref.md   ← detail the agent reads only when needed
    scripts/helper.py        ← executed only when SKILL.md calls for it
    assets/template.html     ← loaded only when producing that kind of output

The SKILL.md is the onboarding script. The references/ folder is the shelf of manuals the new hire can pull down when they hit a specific task. The scripts/ folder is the set of tools they are allowed to use once they are trained on them. All of it is accessible — but not all of it is in their head at once.

A second architectural decision flows from this. When multiple specialists need the same reference content, do not duplicate the content inside each specialist's folder. Move it to its own top-level SKILL.md and have the other specialists reference that skill by path. One source of truth. Every specialist pulls the content the same way. When the standard changes, one file changes.

This is exactly the refactor that works in production — and the reason promoting shared references to peer specialist skills makes the agent more reliable, not less.

05 Composition Pattern: Skills Referencing Skills

Once specialists are lean and focused, the next question is how they coordinate. Two composition patterns answer it. The first is skill-to-skill referencing.

Every SKILL.md declares its dependencies in a standard block near the top:

**Depends on:** `jetxmedia-brand` (loads voice, banned phrases, ICPs)
**Also loads:** `skills\deliverable-design-develop-wcag\SKILL.md`
                when delivering HTML/CSS/JS

Two things to be honest about here. This declaration is a coordination convention, not an automatic loader. The Skills system does not parse that line and pull the named skill into context on its own. The declaration does two things instead: it documents the relationship for humans maintaining the stack, and it prompts the agent, while reading the current SKILL.md, to consider loading the referenced skill if the current task calls for it.

In practice this works because the agent is reading the SKILL.md anyway, and an explicit instruction like "also apply the accessibility skill when producing HTML" is a prompt the agent follows the same way it follows any other instruction in the file.

The master-plus-specialists pattern scales this. A master skill does not contain the rules. It contains the routing table that tells the agent which specialists to apply for which deliverable.

A landing-page build pulls in accessibility, UI/UX, responsive, and frameworks. A client blog post pulls in brand-voice and blog-writer. The master skill is the new hire's manager, pointing them at the right specialist playbook for the task in front of them.

This pattern has three benefits. Each specialist can be updated in isolation without touching the others. The master stays small and readable. And the agent only loads the specialists it actually needs for the current task, which preserves context for the work itself.

06 Composition Pattern: Users Calling Skills

The second composition pattern is user-initiated. When a user asks for something, the agent matches the request against every skill's description field in the YAML front matter and decides which skill — or which combination of skills — to load.

This makes the description field the single most important line in a SKILL.md file. A weak description means the skill never triggers. A strong description means the skill triggers reliably on the exact kinds of requests it was built for.

description: "A skill for writing stuff."

description: "Writes SEO-optimized blog posts. Use
for any request to write, draft, outline, or research
a blog post. Trigger phrases: 'write a blog post',
'draft a blog', 'blog about', 'write an article',
'content for the website', 'thought leadership piece'."

The good version does three things. It states the skill's job specifically. It names the output. And it lists the exact phrases the agent should match on. When a user says "write a blog post about our new service," the agent matches the phrase and loads the skill. When the user says "write something," the agent does not.

This is the mechanism that turns a skill into a hyper-focused task executor. A user calling out a proposal skill gets a proposal in the right voice, following the right structure, with the right pricing conventions — because the skill's description triggered on "write a proposal," the skill loaded its rules, and the rules produced the output.

The practical rule: list six to ten specific phrases that should trigger the skill, and name the skill's output in concrete terms. "Produces a publish-ready blog post" is better than "helps with content."

07 Architecture Rules for Writing a SKILL.md

The patterns above collapse into ten concrete rules for authoring a new SKILL.md:

01. One skill, one job. If it does three things, split it into three skills.
02. Keep the SKILL.md lean. Move detail into reference files that load
    only when the SKILL.md tells the agent to read them.
03. YAML front matter first. Name and description are the trigger contract.
04. Write the description for discovery. List six to ten specific trigger
    phrases. Name the output.
05. Declare dependencies at the top of the body. Use the standard
    Depends on / Also loads format as a coordination convention.
06. Inherit generalist rules from CLAUDE.md. Never duplicate naming or
    workflow rules inside a SKILL.md.
07. Group rules under ## sections. Never go deeper than ###.
08. Include one Good and one Bad example for any rule that is easy
    to misread.
09. End with a QA checklist the agent runs before declaring the work done.
10. When shared content is needed by multiple specialists, promote it
    to its own top-level SKILL.md instead of duplicating it.

These rules describe a SKILL.md that loads reliably, references peers cleanly, and produces consistent output regardless of which user triggers it.

They also describe a skill that stays maintainable. When a specialist is lean and focused, future edits are surgical. When a specialist is a monolith with nested helpers and duplicated rules, every edit risks breaking something downstream.

One rule that is not on the list but should be: expect to rewrite. CLAUDE.md and SKILL.md files are not write-once artifacts. They are living documents that get better with each pass. Spending two weeks rewriting before the architecture clicks is not an outlier — it is normal. The first draft will be wrong. The third draft will be closer. By the fifth or sixth pass, the agent starts producing output that feels like it came from a careful senior employee rather than a new hire.

Product managers with years of experience writing onboarding documents for human teams have an unfair advantage here. The skills that make a clear employee handbook — imperative voice, specific examples, no vague qualifiers, one rule per line — are the same skills that make a SKILL.md the agent actually follows.

08 The Takeaway

A well-architected Cowork stack looks like this: one CLAUDE.md at the top — short, generalist, strict. A collection of SKILL.md files below — each hyper-focused on a single discipline, each written lean with detail stored in loadable references, each triggered by explicit phrases the user actually says.

The generalist layer sets the ground rules. The specialist layer runs the task. Progressive disclosure is not a restriction; it is the architectural discipline that keeps specialists small enough to stay accurate.

The mental model that makes all of this click is the onboarding model. Claude Cowork is a brand-new employee — it knows nothing, needs to be taught everything, and operates only inside the guardrails you set. The generalist layer is the orientation session. The specialist layer is the role playbook. Cross-references are the manager pointing at the right manual. Progressive disclosure is the shelf of manuals sitting on the new hire's desk, ready when they are needed.

Write for that employee. Iterate until the agent becomes that employee. The architecture follows from the mental model, and the output speaks for itself.