Skip to main content
MindStudio
Pricing
Blog About
Log in Get Started
My Workspace

Claude Code Skills Architecture: Why Your skill.md File Should Only Contain Process Steps

Most Claude Code skills fail because everything is crammed into skill.md. Here's the correct architecture: process in skill.md, context in reference files.

MindStudio Team
Claude Code Skills Architecture: Why Your skill.md File Should Only Contain Process Steps

The Problem With How Most People Structure Their Claude Code Skills

If you’ve built more than a handful of Claude Code skills, you’ve probably noticed a pattern: the first few work fine, but as they grow more complex, they start behaving inconsistently. Claude follows the steps sometimes, ignores context other times, and the whole thing feels brittle.

The root cause is almost always the same. Everything — the process steps, the background context, the rules, the examples, the edge cases — is crammed into one skill.md file. It seems logical. One file, one skill. But this structure fights against how Claude Code actually processes instructions.

The correct architecture separates concerns: process goes in skill.md, context goes in reference files. This article explains why that distinction matters, how to implement it correctly, and what you should put where.

What Claude Code Skills Actually Are

Before getting into architecture, it helps to understand what a skill actually is in Claude Code’s model.

A skill is a structured set of instructions that tells an AI agent how to perform a specific, repeatable task. In Claude Code, skills are defined through markdown files that agents load at runtime. When Claude Code encounters a skill, it reads the file, internalizes the instructions, and executes accordingly.

The skill.md file is the entry point. It’s what Claude Code reads first when a skill is invoked. Think of it as the agent’s working memory for that particular task — the instructions it actively holds and follows as it works.

Why the Entry Point Distinction Matters

Working memory in language models is not infinite, and it’s not equally weighted. Instructions near the top of a prompt receive more consistent attention than instructions buried deep in a long document. When your skill.md is a 2,000-word document mixing process steps with background context and example data, several things happen:

  • Critical steps get buried under context
  • The model has to do extra work to filter what’s procedural vs. what’s informational
  • Long files push important instructions past the point of reliable attention
  • Editing becomes fragile — changing one section can accidentally affect how the model interprets another

When skill.md focuses on process, Claude knows exactly what to do with it. When it doubles as a knowledge base, the model has to make judgment calls about which parts are instructions and which are background — and it doesn’t always get that right.

The Core Architecture: Process vs. Context

The fundamental principle of well-structured Claude Code skills is the separation between what to do and what to know.

Process = the ordered steps Claude should follow to complete the task. This belongs in skill.md.

Context = the background information, rules, domain knowledge, examples, and reference data Claude needs to execute those steps correctly. This belongs in reference files.

This isn’t just organizational preference. It maps directly to how language models process instructions. When you give Claude a clear procedural list, it can follow it reliably. When you interleave procedure with context, the model has to mentally separate those categories before it can act — and that parsing step introduces errors.

What “Process Steps” Actually Means

Process steps are not vague descriptions of goals. They are explicit, ordered, executable instructions.

Bad process step (too vague):

Analyze the user's content and determine the best approach.

Good process step (explicit and executable):

1. Read the input file provided by the user.
2. Identify the document type (blog post, email, technical doc, or other).
3. Extract all section headings and store them as a list.
4. For each heading, evaluate whether it contains a keyword from the target list.
5. Output a report listing headings that match and those that do not.

The good version leaves no ambiguity about what Claude should do next. There’s no judgment call required about what “analyzing” means.

What “Context” Actually Means

Context is everything else. Some examples:

  • Brand guidelines (voice, tone, restricted phrases)
  • Domain definitions (what counts as a “lead” vs. a “prospect” in your specific context)
  • Examples of good and bad outputs
  • Edge cases and how to handle them
  • Data schemas or format specifications
  • Background knowledge the agent needs to make correct decisions

None of these tell Claude what to do. They tell Claude what to know while doing it. That distinction determines where they belong.

How to Structure Your skill.md File

A well-written skill.md file has a tight, predictable structure. Here’s the pattern that works consistently:

The Four-Part skill.md Template

1. Skill Description (2–4 sentences max)

A concise statement of what this skill does and when it’s used. This is not documentation for humans — it’s context for Claude so it understands the scope of what it’s being asked to do.

## Skill: Content Audit

This skill reviews a draft blog post against the editorial checklist and outputs a structured feedback report. Use this when a writer submits a draft for review before it moves to the editor queue.

2. Prerequisites / Inputs

List what inputs the skill requires before it can run. Be explicit about format and source.

## Inputs Required

- `draft_file`: The blog post draft in markdown format
- `checklist_ref`: Path to the editorial checklist reference file
- `author_name`: The name of the author (string)

3. Process Steps (numbered, ordered, explicit)

This is the core of the file. Every step should be actionable. If a step requires Claude to consult a reference file, the step should say so explicitly, including the file path.

## Process

1. Load `checklist_ref` and store all checklist items as a working list.
2. Read `draft_file` from start to finish.
3. For each checklist item, evaluate whether the draft passes or fails. Use the scoring criteria in `checklist_ref` for borderline cases.
4. Identify the top three issues by severity using the severity definitions in `reference/severity-levels.md`.
5. Draft the feedback report using the template in `reference/feedback-template.md`.
6. Output the completed report to the user.

4. Output Specification

Define exactly what the output should look like. Format, structure, length constraints.

## Output

Return a structured markdown report with:
- A pass/fail summary table (one row per checklist item)
- A "Top Issues" section listing the three most critical problems
- An "Action Items" section with specific, numbered edits for the author

Do not include commentary outside this structure.

That’s it. Nothing else belongs in skill.md.

Building a Reference File System

Reference files are where your skills get their intelligence. A well-organized reference file system is the difference between a skill that runs mechanically and one that consistently produces high-quality outputs.

Organizing Your Reference Directory

A clean reference file structure for a set of skills might look like this:

/skills/
  content-audit/
    skill.md
    /reference/
      editorial-checklist.md
      severity-levels.md
      feedback-template.md
      brand-voice-guide.md

Each reference file serves one purpose. That’s not an arbitrary rule — it’s a practical constraint. When a reference file contains multiple types of information, you make Claude’s job harder. The model has to locate and extract the right information within a larger document rather than reading a focused file that tells it exactly what it needs.

Types of Reference Files You Should Have

Rules files — Constraints and requirements that apply to the skill’s outputs. Examples: content policies, character limits, prohibited phrases, required disclaimers.

Definition files — Taxonomies and terminology your domain uses that Claude might not interpret the same way you do. If “qualified lead” means something specific in your organization’s context, that goes in a definitions file.

Template files — Output structures the skill should produce. Instead of describing the format in skill.md, store the template as a reference file and instruct Claude to use it.

Example files — Sample inputs and outputs showing what good looks like. These are especially useful for skills that produce creative or judgment-heavy outputs where “correct” is subjective.

Data files — Structured data the skill needs to reference: keyword lists, product names, pricing tiers, approved vendor lists.

Writing Good Reference Files

Reference files should be written for the model, not for humans. That means:

  • Be literal. Don’t assume Claude will infer what you mean. If a severity level of “critical” means Claude should flag the issue and stop the process, say that explicitly.
  • Use clear hierarchies. Headers and subheaders help Claude locate information within a larger file.
  • Avoid ambiguity. Terms like “appropriate,” “good,” and “standard” don’t mean anything without a definition. Replace them with specifics.
  • Include negative examples where helpful. Telling Claude what not to do is often as useful as telling it what to do.

Here’s a poorly written reference file entry:

## Tone Guidelines
Content should be professional and appropriate for our audience.

Here’s a better version:

## Tone Guidelines

**Voice:** Direct, clear, and conversational. Address the reader as "you."

**Formality level:** Casual-professional. Write as a knowledgeable colleague explaining something to a peer, not as a consultant writing a report.

**Avoid:**
- Passive voice constructions
- Hedging language ("might," "possibly," "could potentially")
- Jargon that would be unfamiliar to someone outside the industry

**Do not use these specific phrases:** [link to prohibited-phrases.md]

How Claude Code Loads and Processes These Files

Understanding how Claude Code actually handles files at runtime helps explain why this architecture works.

When a skill is invoked, Claude Code assembles a context window from:

  1. The system prompt (which may include global agent instructions)
  2. The skill.md file
  3. Any files explicitly referenced in the skill or loaded by the agent

The critical point is that files don’t automatically get loaded. Your skill.md process steps need to explicitly instruct Claude to read specific reference files. This is not a limitation — it’s a feature. It means you control exactly what context is available at each stage of a process.

Explicit vs. Implicit File Loading

Consider these two approaches:

Implicit (problematic):

## Process

1. Review the draft for tone issues.
2. Check all claims against our fact-checking standards.
3. Output the review report.

Claude doesn’t know where the tone guidelines are, what the fact-checking standards are, or what format the report should take. It will improvise — and improvisation is where consistency breaks down.

Explicit (correct):

## Process

1. Load `reference/tone-guidelines.md`. Review the draft against every guideline listed in the "Active Rules" section.
2. Load `reference/fact-check-standards.md`. For every factual claim in the draft, verify it meets the standards listed under "Verification Requirements."
3. Load `reference/report-template.md`. Complete the template with your findings from steps 1 and 2.
4. Output the completed report.

This version leaves nothing ambiguous. Claude knows what to load, when to load it, and what to do with it.

Context Window Management

One practical advantage of this architecture: you can load reference files conditionally. If your skill has a branching process (do X for type A, do Y for type B), you can instruct Claude to load different reference files depending on what it finds.

3. Identify the document type.
   - If "technical documentation": load `reference/tech-doc-standards.md`
   - If "marketing copy": load `reference/marketing-standards.md`
   - If "internal memo": load `reference/internal-format.md`

This keeps irrelevant context out of the working window and ensures Claude is always working with the most relevant guidelines for the task at hand.

Common Architecture Mistakes and How to Fix Them

Most Claude Code skill failures trace back to a small set of architectural errors. Here’s what they look like and how to correct them.

Mistake 1: Using skill.md as a Knowledge Dump

What it looks like: A skill.md file that is hundreds of lines long, containing brand guidelines, examples, background context, definitions, edge cases, and process steps all in one document.

Why it fails: Claude processes the file as instructions. When process steps are surrounded by paragraphs of background information, the model’s attention gets fragmented. It may treat context as instruction or miss procedural steps entirely.

Fix: Move everything that is not a process step into reference files. Your skill.md should shrink significantly. If it’s still over 150 lines, you’ve probably left too much context in it.

Mistake 2: Vague Process Steps That Require Inference

What it looks like: Steps like “review for quality,” “ensure compliance,” or “improve as needed.”

Why it fails: These instructions require Claude to decide what “quality,” “compliance,” and “improvement” mean. Without explicit criteria, the model defaults to general training data — which may not match your organization’s standards.

Fix: Every step that involves evaluation or judgment should reference a specific file that defines the criteria. “Ensure compliance” becomes “verify the output meets every requirement listed in reference/compliance-checklist.md.”

Mistake 3: Inconsistent Reference File Naming

What it looks like: Reference files named things like guidelines.md, info.md, stuff.md, or varying naming conventions across different skills.

Why it fails: When your skill.md instructs Claude to load reference/tone-guide.md but the file is actually called reference/tone-guidelines.md, the skill fails. Also, inconsistent naming makes it hard to build skills that share reference files across a library.

Fix: Adopt a naming convention and apply it everywhere. A simple convention:

  • [topic]-rules.md — for constraints and requirements
  • [topic]-definitions.md — for terminology and taxonomy
  • [topic]-template.md — for output structures
  • [topic]-examples.md — for sample inputs/outputs

Mistake 4: Not Versioning Reference Files

What it looks like: A single reference file that gets edited directly whenever guidelines change.

Why it fails: Changes to reference files affect every skill that loads them. A small edit to brand-voice-guide.md can unexpectedly change the output of five different skills.

Fix: Version reference files when you make significant changes. Keep prior versions accessible. Before changing a shared reference file, audit which skills load it and test those skills after the change.

Mistake 5: Process Steps That Mix Execution and Explanation

What it looks like:

4. Review the draft for keyword usage. Keywords are important for SEO and should appear naturally throughout the content. High keyword density can hurt rankings while low density misses opportunities. Check that the primary keyword appears 2–4 times per 1,000 words.

Why it fails: The procedural instruction (check keyword density) is buried inside an explanation. Claude has to parse what’s background information and what’s the actual instruction.

Fix: Put the explanation in a reference file. Keep the step minimal:

4. Check keyword density against the thresholds in `reference/seo-requirements.md`. Flag any keywords that fall outside the acceptable range.

Scaling Your Skills Library

Individual well-structured skills are valuable. A well-structured library of skills that share reference files and build on each other is exponentially more powerful.

Building Shared Reference Files

Some reference content applies across many skills. Brand voice guidelines, company policies, common data schemas, and output templates are candidates for shared reference files.

Structure your directory to make shared files obvious:

/skills/
  /shared-reference/
    brand-voice.md
    prohibited-phrases.md
    output-formats.md
    compliance-rules.md
  /content-audit/
    skill.md
    /reference/
      checklist.md  (skill-specific)
  /content-creation/
    skill.md
    /reference/
      brief-template.md  (skill-specific)

Skills that need brand guidelines load ../../shared-reference/brand-voice.md. Skills that need skill-specific context load from their local /reference/ folder.

Skill Composition

Once your skills are properly structured, you can start building meta-skills — skills that orchestrate other skills.

## Skill: Full Content Production Pipeline

## Process

1. Run `skills/brief-development/skill.md` with the client inputs.
2. Use the output brief as input for `skills/content-drafting/skill.md`.
3. Run the draft through `skills/content-audit/skill.md`.
4. If the audit outputs any "critical" issues, return to step 2 with the audit report as additional context.
5. If no critical issues, run `skills/final-formatting/skill.md` and output the finished piece.

This kind of composition only works reliably when each underlying skill is clean, consistent, and produces predictable outputs. That’s another reason architecture matters — it’s the foundation that makes more advanced patterns possible.

Documenting Your Library

As your skills library grows, add a top-level README.md that lists available skills, what they do, what inputs they require, and which shared reference files they use. This isn’t just for human developers — you can reference this document in meta-skills to give Claude a map of available capabilities.

Where MindStudio Fits Into This Architecture

If you’re using Claude Code skills as part of a larger agent workflow — where skills are one layer in a multi-step automated process — the skills architecture problem becomes more visible. Individual skill quality matters, but the infrastructure around those skills matters just as much.

This is where MindStudio becomes relevant. MindStudio’s Agent Skills Plugin is an npm SDK that lets AI agents like Claude Code call over 120 pre-built capabilities as simple method calls — things like agent.sendEmail(), agent.searchGoogle(), or agent.runWorkflow(). The SDK handles auth, rate limiting, and retries so the agent’s context window stays focused on reasoning through the task, not managing plumbing.

From a skills architecture perspective, this matters because one of the main reasons skill.md files get bloated is that developers try to encode infrastructure logic inside skill instructions. Steps like “retry if the API returns a 429 error” or “check whether the email sent successfully before proceeding” don’t belong in skill.md — they’re infrastructure concerns, not process concerns.

When Claude Code agents are backed by MindStudio’s infrastructure layer, those concerns are handled externally. The skill can stay focused on process. skill.md can say “send the completed report to the user’s email” without needing to specify retry logic, error handling, or authentication — the SDK manages all of that.

The result is cleaner skills that are easier to maintain, easier to debug, and more consistent in execution. You can try MindStudio free at mindstudio.ai and connect it to your Claude Code skills via the @mindstudio-ai/agent package.

Frequently Asked Questions

What should skill.md contain?

skill.md should contain exactly four things: a brief description of what the skill does, the inputs it requires, the numbered process steps in execution order, and the output specification. Everything else — context, rules, examples, templates, domain knowledge — should live in reference files that the process steps load explicitly.

If your skill.md includes background information, guidelines, examples, or explanations that aren’t part of the execution sequence, those should be moved to reference files.

How long should skill.md be?

There’s no strict rule, but a well-structured skill.md is typically 40–100 lines. If yours is significantly longer, it’s likely because context has leaked into the process file. The process steps themselves should be concise and directive. Most of the content length should come from your reference files, not from skill.md.

How do I get Claude to consistently load reference files?

The reference file loading needs to be an explicit step in your process. Don’t assume Claude will load files automatically. Each step that requires context from a reference file should name the file path explicitly and say what Claude should do with it (e.g., “Load reference/tone-guide.md and apply every rule in the ‘Active Guidelines’ section”).

Also make sure file paths in your process steps match the actual file names and directory structure. A path mismatch is the most common cause of reference files not loading.

Can multiple skills share the same reference files?

Yes, and this is a good practice. Shared reference files for brand guidelines, compliance rules, output templates, and common definitions reduce duplication and make it easier to update standards across your entire skills library in one place. Structure your directory with a /shared-reference/ folder at a level above individual skills, and reference files by relative path.

What’s the difference between a CLAUDE.md file and skill.md?

CLAUDE.md (or claude.md) is typically a project-level or repository-level file that Claude Code reads to understand the overall context of a project — coding conventions, architecture decisions, repository structure, and working norms. It’s persistent project context.

skill.md is task-specific. It defines how to execute a particular skill — the inputs, steps, and outputs for one specific type of work. A project might have one CLAUDE.md and many skill.md files for different tasks. The skills can reference the CLAUDE.md context, but they’re separate concerns.

How do I handle edge cases in this architecture?

Edge cases belong in reference files, not in skill.md. Create an edge-cases.md or special-handling.md reference file and include a step in your process that says “If the input doesn’t match any of the standard document types, consult reference/edge-cases.md for handling instructions.” This keeps your process steps clean while making edge case handling explicit and maintainable.

Should I use YAML frontmatter in my skill files?

Some Claude Code implementations support YAML frontmatter in skill files for metadata like skill name, version, author, and tags. This can be useful for skills library management, especially as your library grows. If you use it, keep it minimal and don’t put executable instructions in frontmatter — those belong in the process steps section.

Key Takeaways

  • skill.md is for process, not knowledge. If it doesn’t tell Claude what to do next, it probably belongs in a reference file.
  • Explicit is always better than implicit. Every reference file load should be a named step that specifies the file path and what to do with the content.
  • Short, focused reference files beat long, mixed-purpose ones. One file per concern makes it easier to maintain and easier for Claude to locate the right information.
  • Vague process steps produce inconsistent results. Every step that involves evaluation or judgment should point to explicit criteria in a reference file.
  • A clean skills architecture scales. Well-structured individual skills can be composed into pipelines, shared reference files can govern multiple skills, and the whole library becomes easier to maintain and debug.

Getting this architecture right isn’t just good hygiene — it’s the difference between skills that work occasionally and skills that work reliably. The pattern is straightforward once you see it: process in skill.md, context in reference files. Everything else follows from that.

If your current skill.md files are doing more than they should, the fix is usually just reorganization. Pull the context out, put it in dedicated reference files, update your process steps to load those files explicitly, and watch your skills become noticeably more consistent.

And if you’re building Claude Code agents that need to do real-world work — sending emails, searching the web, triggering workflows — MindStudio gives you a clean infrastructure layer so those capabilities stay out of your skill logic and your skill.md files stay focused on what they’re actually for.