5. Building and Expanding a Skill

🎥 Video lesson — video not yet migrated (source Skool video id: 133402379e8f4e9abf5a600ed560bb08).

You've built a basic plugin in Cowork. Now you build a real one.

CW-5 covers the three files that go into every plugin — the agent identity, the SKILL.md capability menu, and the first working capability — plus the discipline of testing before declaring anything done.

🗂️ The mental model A plugin is an organisational chart rebuilt in AI. Each file has a specific role. The agent file defines who the agent is. The SKILL.md is a router — it tells the agent what capabilities it has and which file to read for each one. The capability files are the actual steps. Each one is a bite-sized, testable piece of the workflow.

🎯 What you'll build → agents/1-content-strategist.md — who this agent is, what it does and doesn't do, how it behaves → skills/1-content-strategist/SKILL.md — the capability menu that routes between your 5 workflow steps → load-context.md — the first capability: Phase 1 of the content ideation workflow

🔧 The 3-fix pattern Every capability file ships at 60% consistency by default. Three additions close that gap before you run a single test: → Output format — the exact structure Claude returns, every time → Worked example — one complete input → output pair inline → Constraints — what NOT to produce

Run it once without these. Then add them and run it again. The difference makes the argument better than explanation.

🔄 The 80/20 iteration loop BUILD → TEST (5+ diverse inputs) → REVIEW (classify the failure) → REFINE (smallest fix) → TEST AGAIN

Exit when 4 of 5 inputs produce output you'd actually use. Ship at 80%.

⛓️ Where this is heading The reason you build capabilities as separate files isn't busywork — it's so you can test and refine each step individually. Once a capability performs reliably 8–9 times out of 10, you start chaining them. That's when your plugin becomes an agentic workflow: Claude making decisions across multiple steps with no human in the loop. You build that reliability one capability at a time.

✅ What you'll leave with A tested, working first capability — not a perfect one. A good one. And the habit of running the loop before declaring anything done.

→ Next up: CW-6 — References, Context, and Scoring. You'll add the files that make your plugin produce output in the right voice for the right audience, then build the next two capabilities.

PART 2 — LESSON BODY (full markdown, paste into Skool lesson page)

Building the plugin

Up to this point you've covered the fundamentals — what a plugin actually is, what skill files are, how to build a basic use case directly in Cowork, and how to map a process in granular detail. Now you execute.

This time you're building a more detailed, more modular version of the content plugin — one that reflects how a real workflow is structured. By the end of this lesson you'll have a tested, working first capability.

The mental model before you write a single file

A plugin is an organisational chart rebuilt in AI. Think about it that way: you're not writing code, you're defining roles, responsibilities, and handoffs — the same thing you'd do if you were hiring a team.

Three files. Three distinct roles.

Agent file (agents/1-content-strategist.md) — defines who this agent is. Its role, its scope, its behaviour. This file is always in context, so keep it lean. It's the permanent character.

SKILL.md — the router. When a skill activates, SKILL.md is the first file Claude reads. It doesn't explain how to do anything — it lists the capabilities available and which file handles each one. That's it.

Capability files (load-context.md, generate-concepts.md, etc.) — the actual work. Each capability file is one step in your workflow. It loads on demand when that step is triggered.

One practical note on shared context: at this point in Cowork's plugin infrastructure, context stays inside each plugin. Brand voice, ICP profiles, and brand guidelines can't be shared directly between your content plugin and your marketing plugin — you'd duplicate the reference files. This is the current limitation and it'll likely be patched. For now, duplication is the approach: straightforward to do, and AI copies files quickly.

Step 1 — Fill in your agent identity

Open agents/1-content-strategist.md. This was created empty in CW-3. Here's what it needs:

---
name: content-strategist
description: >
  Use this agent when the user wants to research content ideas, develop a
  content concept, score ideas against their audience, or map a concept
  across platforms. Handles the full content ideation workflow end to end.
model: inherit
color: violet
skills: [1-content-strategist]
---

## Role

You are a content strategist. You help creators, marketers, and agency owners
develop content concepts grounded in their brand, audience, and research.

## What you do

- Load brand and audience context before beginning any work
- Develop content concepts informed by research and ICP profiles
- Score and rank concepts against the ICP alignment scoring guide (ICP relevance, brand alignment, funnel fit, technical depth, uniqueness)
- Map winning concepts across target platforms with distinct angles per platform
- Compile a complete concept brief for downstream production

## What you don't do

- You don't write full drafts — the Copywriter agent handles that
- You don't create ad creative or paid social content
- You don't publish or schedule — the Publisher agent handles that

## Tone and behaviour

- Collaborative, not directive. This is a partnership.
- Be specific: name the platform, name the hook angle, name the audience segment
- Short paragraphs. No preamble. Get to the thinking.

## Skills you can invoke

- 1-content-strategist: the full content ideation workflow

Two things to understand here.

The description frontmatter field is what Claude reads to decide whether to activate this agent. A vague description like "helps with content" causes Claude to skip it for ambiguous requests. A specific trigger list tells Claude exactly when this agent is relevant. Write the description for Claude, not for humans.

The body — role, what you do, what you don't do, tone — is the permanent character. It loads every time any capability runs. Keep it lean. One paragraph sections. The agent file is not the place for task instructions.

Step 2 — Fill in SKILL.md

Open skills/1-content-strategist/SKILL.md. This is the first file Claude reads when the skill activates. It's a router, not a manual.

---
name: 1-content-strategist
description: >
  Use this skill when the user wants to develop content ideas, run the content
  ideation workflow, score concepts against their ICP, map content across
  platforms, or compile a concept brief for production. Activates on intent
  to create, plan, or strategise content.
version: 1.0.0
---

# Content Ideation

On activation, check for active project context. Then present the workflow menu:

**Content Ideation — 5 phases:**

**[LC] Load Context** — Load brand voice, ICP profile, and research. Confirm context before beginning.
**[GC] Generate Concepts** — Develop 3-5 content concepts grounded in loaded context.
**[SR] Score and Rank** — Score each concept using the ICP alignment scoring guide from `references/icp-profile.md`. Five criteria: ICP relevance (30%), brand alignment (25%), funnel fit (20%), technical depth (15%), uniqueness (10%). 80%+ = green light. 60–79% = refine. Below 60% = kill.
**[CT] Content Tree** — Map the winning concept across all target platforms with distinct angles.
**[CB] Compile Brief** — Assemble the complete concept brief and save to output file.

Run sequentially: LC → GC → SR → CT → CB.

Or run from the current phase if resuming an in-progress session.

The description frontmatter precision beats body length every time. The body is a table of contents — it lists the 5 capabilities and tells Claude to run them sequentially. It does not contain the capability instructions themselves. Those live in the individual capability files, which load on demand.

List all 5 capabilities now even though you're only building load-context.md today. When you build the remaining files in CW-6 and CW-7, Claude will be able to route to them automatically because the menu already exists.

Capabilities are workflow steps

Before you write the first capability file, lock in this mental model: a capability is one step in a workflow.

Your process map from CW-4 has steps. Each step becomes a capability file. The SKILL.md lists them all. When you trigger a capability, Claude reads that specific file and executes that specific step — nothing else.

The reason you separate them isn't structure for its own sake. It's so you can test and refine each step individually. When you first run a capability, it'll probably perform at 60–70% accuracy. You test it, review what's off, and update that one file until it reaches 8–9 times out of 10. Then you move to the next capability.

Once your capabilities are each performing reliably on their own, you start chaining them together — and that's when your plugin becomes an agentic workflow. Claude makes decisions across multiple steps with no human in the loop. That's what "agentic" actually means. But it almost never works right out of the box. You get there by building manual, testing manual, and only chaining what's proven reliable. The separation is what makes the progression possible.

**Step 3 — Write your first capability: **load-context.md

Create skills/1-content-strategist/load-context.md. This is Phase 1 of your process map.

A capability file has 4 parts: the purpose statement, the process steps, the output format, and the example + constraints.

The purpose statement

# [LC] Load Context

## Purpose

Load brand, audience, and research context before content ideation begins. Confirm with the user before proceeding to concept generation.

The process steps

## Process

1. Welcome the user and explain what this phase does.
2. Load brand voice from `${CLAUDE_PLUGIN_ROOT}/references/brand-voice.md`.
   Load ICP profile from `${CLAUDE_PLUGIN_ROOT}/references/icp-profile.md`.
   Load platform spec from `${CLAUDE_PLUGIN_ROOT}/references/platform-spec.md`.
   If any file is missing, halt and explain what's needed before continuing.
3. Search the current project folder for a competitive research report.
   If found, offer to load it. If not found, ask the user: "What topic or direction
   would you like to explore today?"
4. Check: "Have you already filmed a video for this content piece?"
   - Yes → ask for the transcript or a transcript file path. Store as footage context.
   - No → continue to context confirmation.
5. Present a context status table. Wait for [C] Continue before proceeding.

The output format

This is where most capability files are vague. Don't write "confirm the context" — write exactly what the output looks like:

## Output format

Present a status table with these exact rows:

| Context | Status | Detail |
|---------|--------|--------|
| Brand Voice | Loaded / Missing | File path or error |
| ICP Profile | Loaded / Missing | File path or error |
| Platform Spec | Loaded / Missing | File path or error |
| Research | Found / Not found | File name or "none" |
| Footage | Yes / No | "Transcript loaded" or "scratch mode" |

Then display:

"Context loaded. Ready to generate concepts.

[C] Continue → Phase 2: Generate Concepts"

The worked example

## Example

INPUT: User activates LC. Brand voice, ICP profile, and platform spec all exist in references/. No research report found. User says "No" to footage. Topic: AI agency pricing.

OUTPUT:

| Context | Status | Detail |
|---------|--------|--------|
| Brand Voice | Loaded | references/brand-voice.md |
| ICP Profile | Loaded | references/icp-profile.md |
| Platform Spec | Loaded | references/platform-spec.md |
| Research | Not found | None in project folder |
| Footage | No | Scratch mode — topic: AI agency pricing |

Context loaded. Ready to generate concepts.

[C] Continue → Phase 2: Generate Concepts

The constraints

## Constraints

- Do not proceed to Phase 2 until the user selects [C] Continue
- Do not assume context files exist — check all three (brand-voice.md, icp-profile.md, platform-spec.md) before loading
- Do not invent brand voice, ICP data, or platform specs if files are missing — halt and explain what's needed
- Do not skip the footage check

The 3-fix pattern

Look at what you just wrote. The output format, worked example, and constraints aren't decorative. They do three different jobs — and the difference between having them and not having them is the difference between a capability that performs at 60% and one that performs at 90%.

Here's what that difference looks like:

Output format

❌ Vague✅ Clear"Confirm the context has been loaded."Exact table with 5 rows, specific column names, specific status values (Loaded / Missing), plus the exact [C] Continue prompt text to display after.

Vague format = Claude improvises a different structure every time. Clear format = locked output, every run.

Worked example

❌ Vague✅ Clear"Show the user what was loaded."A complete input → output pair: specific inputs (no research report, no footage, topic given), exact output table filled in with real values.

No example = Claude guesses what "good" looks like. One real example = Claude pattern-matches against it and adjusts.

Constraints

❌ Vague✅ Clear"Don't skip any steps.""Do not proceed to Phase 2 until the user selects [C] Continue. Do not assume files exist — check all three before loading. Do not invent brand voice if files are missing — halt."

Generic constraints = Claude finds gaps. Specific constraints = specific failure modes closed.

These three fixes are why a capability that works "sometimes" becomes one that works consistently. Add them before you run the first test, not after.

Step 4 — Install and run it once

In Cowork, run the install command for your plugin. Then trigger the skill: type /content and press Enter.

Give it a real input. Not a placeholder. Something you'd actually use today.

Look at the output. Does it match your output format spec? Does the status table appear? Does it halt at [C] Continue?

If it does — good. Take 10 seconds. You wrote a capability file and it directed Claude's behaviour exactly as specified.

Now run it again with a different setup. No research file. No brand voice file yet. What happens?

That's your first real failure. Let's classify it.

Step 5 — The 5-run rule

You haven't tested a capability until you've run it on inputs you didn't write the example for.

Run yours 5 more times with varied inputs:

  • No research file, no footage, ask for topic direction
  • Research file exists, footage provided, transcript attached
  • Short ambiguous input with no clear topic
  • Full context exists, user picks "Yes" on footage but provides no transcript
  • Complete happy path: everything exists, user confirms

Log what breaks. A notes doc works fine. You're looking for patterns.

The 5-run rule isn't about catching every failure. It's about breaking the assumption that the first good output means the capability is reliable.

Step 6 — Classify before you fix

There are 3 failure types. Classify before you touch the file.

Type A: Wrong format — output structure is off. Sections out of order, wrong column names, missing rows, wrong heading level.

  • Fix location: the output format block. Tighten the spec. Show the exact structure.

Type B: Wrong content — format is fine but content misses. Too broad, wrong tone, misses the context that was loaded.

  • Fix location: the constraints section. Add a specific rule. "If brand-voice.md is missing, don't attempt to summarise — halt immediately and list the file path needed." is more effective than rewriting the whole process.

Type C: Inconsistent — sometimes it nails it, sometimes it doesn't. Same input type, variable quality.

  • Fix location: the worked example. A weak or non-representative example is almost always the root cause. Update it to reflect what a strong output actually looks like for the specific failure mode.

Classify, then fix the right section. Don't rewrite the whole file when one constraint would do it.

Step 7 — The 80/20 loop

Here's the loop in its simplest form:

BUILD
  ↓
TEST (5+ diverse inputs — log what breaks)
  ↓
REVIEW (classify: format / content / inconsistent)
  ↓
REFINE (smallest fix to the right section)
  ↓
TEST AGAIN (failing input first, then new ones)
  ↓
Ship when 4 of 5 inputs work correctly

The loop exits at 80%. Not 100%.

Here's why: the last 20% takes 80% of the time, and it's almost entirely edge cases you won't encounter in real use. The real failures surface in production, where you have real context to fix them properly. A capability you've run 50 times needs far less review than one you've run 5 times. That's the compound return on a working iteration habit.

Edit the capability file. Run /reload-plugins in Cowork. Test with the failing input. Repeat. No reinstall needed unless you changed plugin.json.

Once you've applied this loop to each capability in your plugin and they're each performing reliably, the next step is to start chaining them — removing the manual [C] Continue checkpoints and letting Claude run the workflow end to end. That's when it becomes fully agentic. You can't skip to that. You earn it by building the reliability first.

What you've built

content-ideation/
  .claude-plugin/
    plugin.json
  agents/
    1-content-strategist.md    ← filled in
  references/
    brand-voice.md             ← voice rules, forbidden words, anti-AI patterns
    icp-profile.md             ← audience definition + 5-criteria scoring guide
    platform-spec.md           ← format rules and character limits per platform
  skills/
    1-content-strategist/
      SKILL.md                 ← filled in with 5-capability menu
      load-context.md          ← tested, working

One capability down. Four to go. The pattern you've just applied — purpose → process → output format → example → constraints → test → iterate — is the same pattern for every capability you'll ever build, for any workflow in any plugin. Once you understand how to build each of these agents, you can apply it to a copywriter, a LinkedIn post creator, a sales qualifier, anything.

The next two capabilities — Generate Concepts and Score and Rank — come in CW-6. The references folder is already in place: Score and Rank will pull the ICP alignment scoring criteria directly from icp-profile.md, and the Content Tree step will use platform-spec.md to format output correctly per platform.

→ Next: CW-6 — References, Context, and Scoring

← Previous
Next →