PowerUp Coaching — Living Knowledge Base

Insight: Separation of Concerns in Skills — One File, One Job

5 min read

“We want the strategist to be an expert, and only to be able to do strategy. We want the researcher to be the best possible researcher. We don’t want watered-down versions of these guys just to be able to put them in the skill, and we don’t want to bring all of this specification into the skill before we need it.” — Lou

Session context: 2026-04-09_Mastermind — Explained by Lou while building the Brand Writing Team skill live, as a deliberate architectural choice rather than a default that Claude would pick if left to its own judgment.

Core Idea

The instinct when building a complex AI skill is to put everything into one file: all the roles, all the instructions, all the context. It feels cleaner. You have one place to look. But this collapses the quality of every function in the skill because:

  1. Every function has to compete for context space with every other function
  2. Every time the skill runs, even for a simple sub-task, all that context is loaded
  3. You end up with generalists where you need specialists

Lou’s principle — borrowed from software engineering — is separation of concerns: each function gets its own file, with the skill.md acting only as the orchestrator.

The architecture looks like this:

brand-writing-team/
  SKILL.md          ← orchestrator only (decides what to call and when)
  resources/
    researcher.md   ← full researcher specialization
    outliner.md     ← full outliner specialization  
    drafter.md      ← full writer specialization
    editor.md       ← full editor specialization
    brand-voice.md  ← brand voice reference
    avatar.md       ← audience persona

The skill.md doesn’t do any of the writing, researching, or editing. It reads the user’s request, determines which functions are needed and in what order, calls each function (spawning sub-agents as appropriate), handles the handoffs, and delivers the final output. Each function file, by contrast, is allowed to be as specific and detailed as the job demands — 200 lines if that’s what it takes to produce world-class work.

Context efficiency: Only the skill.md header loads into context initially. When a function is needed, its file is loaded. When it’s done, the context moves on. A skill that researches + outlines + drafts + edits never has all four specialist files in context simultaneously — only the one currently working. This is what Lou calls Progressive Disclosure: the skill discloses its resources progressively, on demand, rather than up front.

Parallel execution benefit: Separation makes parallelism possible. If the outliner and the skeptic can work simultaneously (checking structure and checking weak claims in parallel), they can be spawned as concurrent sub-agents. This only works if they’re in separate files with clean boundaries. A monolithic skill can’t be parallelized because its functions aren’t individually callable.

The edit and maintenance benefit: When a client wants to improve the researcher’s sourcing standards but leave the voice and style unchanged, you edit researcher.md. Nothing else changes. With a monolithic skill, improving one function requires reading and carefully editing a file that contains everything else — with the risk of unintended side effects.

Practical Application

The five-minute refactor: If you have an existing complex skill that feels sluggish, context-heavy, or hard to edit, apply this as a refactor:

  1. Open the skill.md
  2. Identify each distinct function (each role or stage)
  3. Extract each function’s instructions into its own file in a resources/ subfolder
  4. Replace the function instructions in skill.md with a one-line reference: “When doing X, load resources/x.md and execute it”
  5. Test with a simple request (one function) to confirm it loads correctly

The skill.md test: A well-separated skill.md should be readable in under 2 minutes. It says what the skill is, what functions exist, when to call them, and how handoffs work. If you need to read more than 2 pages to understand what the skill does at the orchestration level, functions are leaking into the orchestrator.

Evolution Across Sessions

This establishes the baseline for Separation of Concerns as an explicit, named design principle for Claude skills. Prior sessions introduced skill chaining (Insight - Skill Chaining — Build Modular AI Pipelines Instead of Monolithic Prompts) and forked contexts (Insight - Forked Skills as Context Isolation — Run Sub-Agents Without Polluting Your Conversation). This insight names the underlying architectural principle that makes both work: one file, one job. Future sessions should surface examples of members applying this in their own skill refactors and testing whether context efficiency improves as expected.

Graph View

Backlinks