Build a Real Skill — Level Up From a One-Shot Skill to a System

---
name: realmarknews
description: >
  Two-phase RealMarkAI newsletter workflow... Triggers on:
  "realmarknews", "write the newsletter", "publish it"...
---

I want to build a skill for [task]. Before we write anything, help me map the workflow.
Ask me questions until we have every step, the order, and every point where I need to approve
something before it continues.

Turn this map into a Claude Code skill. Create the folder in ~/.claude/skills/,
write the SKILL.md with a name, a clear description, and trigger phrases, and set up the
steps as plain-English instructions. Do not write code yet.

Lay out the steps in order. If part of this should wait for my go-ahead, split it into
two phases: one that prepares and one that sends or publishes.

Before the step that [sends / publishes / spends money / is hard to undo], add a checkpoint:
print what you are about to do and wait for me to confirm. Never do that step without a yes.

I have a template/format/rules for this. Create a references/ file for it and have the
SKILL.md point to it instead of holding all of it inline.

Create a LEARNED.md in this skill's folder and tell the SKILL.md to read it at the start of
every run. Then let's do a test run of the skill on a real example right now.

# Build a Real Skill — Level Up From a One-Shot Skill to a System

60-minute facilitator run-of-show for the July 2026 Smart Agent Collective group call. By the end, every member has taken one real recurring task and turned it into a proper multi-step Claude Code skill: a `SKILL.md` with triggers, a human approval checkpoint, a `references/` file, and a `LEARNED.md` memory file. The RealMarkAI newsletter skill is the worked example we build toward.

**Format:** live build together. Members build in their own Claude Code the whole time.

---

## Before the Call (homework)

Members should already have:
- Claude Code installed and running (`claude` command works in the terminal)
- One recurring, multi-step task in mind that they would like to automate (market report, listing package, weekly email, call follow-up)

**Open with a show of hands:** "Who already has a basic skill from June?" Anyone who does not can still follow along; pair them with the task-picking step in Part 4.

**The one thing to repeat up front:** in June we turned a single task into a one-shot skill. Today we turn a whole workflow into a skill that runs itself, with you in the loop at the right moments. That is the difference between a shortcut and a system.

---

## Part 1: The Idea, From a Shortcut to a System (6 minutes)

**Talk through. No screen share yet.**

### Where we were, where we are going

- June: a skill was plain instructions for one task. Say the trigger, it does the thing.
- July: a real skill has phases, checkpoints, memory, and its own reference material. It handles a task with multiple steps and stops to check with you before anything irreversible happens.

### The worked example: the RealMarkAI newsletter skill

Walk through what it does at a high level (do not open the code yet). Today we focus on the newsletter itself, how it gets created and sent:
- It reads a curated content queue, researches the week's AI news, and drafts the newsletter, but it stops and asks Tom "does this angle work?" before writing a word.
- Once Tom is happy with the draft, it sends the newsletter to the list, but only after a confirm.
- Result: a newsletter that used to take hours now takes under 30 minutes, and it is better because Tom spends his time editing, not building from scratch.

### The one lesson that makes it work

You do not start by writing the skill. You start by mapping the workflow. Map every step you take, the order, and where a human decision has to happen. Then you hand that map to your AI and it builds the skill around it. That is the whole trick.

**Say this line:** "If you can map it, you can build it. If you cannot map it, you do not understand your own process well enough yet, and that is the real work."

---

## Part 2: Anatomy of a Real Skill, Tour the Newsletter Skill (10 minutes)

**Screen share. Open the actual `realmarknews` skill so they see the real thing, not a diagram.**

Show each piece and name why it exists. Keep it fast, this is a tour, not a deep read.

### 1. The `SKILL.md` header (frontmatter)

```
---
name: realmarknews
description: >
  Two-phase RealMarkAI newsletter workflow... Triggers on:
  "realmarknews", "write the newsletter", "publish it"...
---
```

Point out: the `name` is the folder name, the `description` is how the AI decides when to use it, and the trigger phrases are the words that fire it. A vague description means the skill never triggers. This is the single most common mistake.

### 2. Phases with their own triggers

The newsletter splits into a draft phase and a publish phase, each fired by a different phrase, so you draft today and send when you are ready without being forced to do it all in one go. (It has a later repurpose phase too, but that is out of scope for today.)

### 3. The human-in-the-loop checkpoint

Open Step 2.5, the pre-draft checkpoint. Before writing a single word, the skill prints what it plans to use and asks "does this direction work?" and waits. Show the Phase 2 confirm before sending, too.

**Say this:** "The checkpoints are not a weakness, they are the point. The AI does the heavy lifting, you keep the judgment calls."

### 4. The `references/` folder

Show `references/newsletter-sections.md` (the section templates and voice guide) and `references/template-reference.html` (the exact email layout). Big, reusable context lives in reference files so the main `SKILL.md` stays readable.

### 5. The `scripts/` folder

Show `scripts/publish.py`. Some steps should be exact and repeatable every time (sending the email, encoding the payload). Those become small scripts the skill calls, instead of asking the AI to redo fiddly work by hand.

### 6. `LEARNED.md`, the memory loop

Every time Tom corrects the newsletter, the fix gets written to `LEARNED.md`, and the skill reads it at the start of every run. Correct once, never re-explain. Show a couple of real entries.

### The five patterns to name out loud

| Pattern | What it gives you |
|---|---|
| Phases + triggers | Break a big job into callable pieces |
| Human checkpoints | AI does the work, you keep control |
| `references/` files | Keep templates and rules out of the main file |
| `scripts/` for exact work | Deterministic steps run the same every time |
| `LEARNED.md` memory | Corrections stick, quality climbs over time |

---

## Part 3: Prerequisites and Dependencies Check (5 minutes)

**Talk through, with a show of hands. This is the "what do you need before you build" gate.**

Before anyone builds a skill like the newsletter one, they need three kinds of things. Walk the group through each and have them confirm they have them.

### A. Member prerequisites (you, before you build)

- Claude Code installed and working
- A code editor open on a folder (VS Code or Cursor), so you can see the files
- One real recurring task you can describe step by step
- A `~/.claude/.env` file for any secrets (never put passwords or API keys in the skill itself)

### B. The skill's own dependencies (accounts and tools the task touches)

The newsletter skill only works because these exist. Your skill will have its own version of each:

| The newsletter skill uses | Your skill's equivalent |
|---|---|
| Notion (curated content queue) | Wherever your source data lives: Notion, a Google Sheet, a folder |
| Gmail API (source newsletters) | Any inbox or feed you pull from |
| Web search (built into Claude) | Same, already available |
| Acumbamail API (sends the email) | Your email tool with an API: Mailchimp, MailerLite, Acumbamail |
| Slack (posts a "done" notification) | Optional: Slack, or just a summary in the terminal |
| Google Tasks (next-edition reminder) | Optional: your task manager |

**Key point:** every external service needs an API key, and every API key goes in `~/.claude/.env`, not in the skill file. Say it plainly: keys in the env file, never in the skill, never in a shared folder.

### C. Sub-skills and building blocks (skills that lean on other skills)

This is where a skill becomes a system. The newsletter skill does not hold everything in one file, it pulls in building blocks:
- It reads brand voice and audience files (`brand-voice.md`, `audience.md`) so the writing sounds like Tom, to the right reader, every time.
- It reads its own section guide (`references/newsletter-sections.md`) for how each part of the newsletter should read.
- It reads `LEARNED.md` at the start of every run so past corrections are always applied.
- As a skill grows, it can also call other whole skills. The newsletter's later phases do this, one skill triggering another. You do not need that today, but know the ceiling is that high.

**Two meta-skills worth knowing** (the skills that help you build skills):
- Ask your assistant to use its skill-writing help when scaffolding a new skill, so it sets up the folder, frontmatter, and trigger correctly the first time.
- Reuse before you rebuild: if a piece of your workflow already exists as a skill in the group (Perfect Cuts, Hyperframes, market report), call it instead of rewriting it.

**Say this:** "You are not building one giant skill. You are building small skills that call each other. That is how mine works, and it is how yours should grow."

---

## Part 4: Live Build, Level Up Your Skill (30 minutes)

**Screen share. Build together, in each member's own Claude Code. Give a time cue at each step and do not move on until most hands are up.**

### Step 1: Pick the task and map the workflow (6 min)

Have each member pick one recurring, multi-step task. Then, before touching Claude, map it. Paper, Excalidraw, or just a list. For each step write:
- What happens
- In what order
- Where YOU have to make a decision or approve something

**Prompt to give the group:**
```
I want to build a skill for [task]. Before we write anything, help me map the workflow.
Ask me questions until we have every step, the order, and every point where I need to approve
something before it continues.
```

Checkpoint: everyone should have a short numbered list of steps with at least one "I approve here" marked.

### Step 2: Scaffold the skill (5 min)

**Prompt:**
```
Turn this map into a Claude Code skill. Create the folder in ~/.claude/skills/,
write the SKILL.md with a name, a clear description, and trigger phrases, and set up the
steps as plain-English instructions. Do not write code yet.
```

Checkpoint: everyone has a `SKILL.md` with frontmatter and a trigger phrase. Have two or three members read their `description` line out loud and tighten any that are vague.

### Step 3: Break it into steps and phases (6 min)

Have the AI lay out the task as numbered steps. If the task is big (draft then send, or build then publish), split it into phases with their own triggers, like the newsletter skill.

**Prompt:**
```
Lay out the steps in order. If part of this should wait for my go-ahead, split it into
two phases: one that prepares and one that sends or publishes.
```

### Step 4: Add a human-in-the-loop checkpoint (4 min)

This is the most important add of the day. Have every member insert one checkpoint where the skill stops, shows its plan, and waits.

**Prompt:**
```
Before the step that [sends / publishes / spends money / is hard to undo], add a checkpoint:
print what you are about to do and wait for me to confirm. Never do that step without a yes.
```

Checkpoint: everyone can point to the line in their skill where it stops and asks.

### Step 5: Add a references file (4 min)

If the task has a template, a format, or rules (a listing layout, an email style, a set of voice rules), move that into a `references/` file so the main skill stays clean.

**Prompt:**
```
I have a template/format/rules for this. Create a references/ file for it and have the
SKILL.md point to it instead of holding all of it inline.
```

### Step 6: Add memory and test it (5 min)

**Prompt:**
```
Create a LEARNED.md in this skill's folder and tell the SKILL.md to read it at the start of
every run. Then let's do a test run of the skill on a real example right now.
```

Run it live. When it gets something wrong (it will), correct it once and have the member tell their assistant to write that correction into `LEARNED.md`. That is the loop that makes the skill better every week.

Checkpoint: everyone has run their skill at least once and has a `LEARNED.md` started.

---

## Part 5: Level Up Next, and Wrap (4 minutes)

### What to add as your skill grows

You do not add these today, but name them so members know the ceiling is high:
- **Scripts** for exact, repeatable steps (sending, formatting, uploading), like the newsletter's `publish.py`
- **API connections** to your real tools (email, CRM, calendar), with keys in `~/.claude/.env`
- **Calling other skills** so one skill can trigger another as your workflow grows
- **A quality check** where the skill scores its own output before showing you, and fixes low scores itself

### Homework

- Finish your skill so it runs your real task end to end
- Add one correction to your `LEARNED.md` after the next real run
- Post in Skool: what task you turned into a skill, and how much time it saved you

### Resources

- Member companion guide (live follow-along, all copy-paste prompts): https://tom.here.now/build-a-skill
- The newsletter skill is the reference architecture for everything above

---

## Facilitator Prep Checklist (before the call)

- Drop the companion guide link in chat at the start and tell everyone to open it in a second window: https://tom.here.now/build-a-skill
- Have the `realmarknews` skill open in your editor, ready to screen share (SKILL.md, references/, scripts/, LEARNED.md)
- Sketch a simple workflow map of the newsletter ahead of time (boxes and arrows: research, draft, checkpoint, send) so you can show what "mapping the workflow" looks like in Part 1
- Pick two or three example tasks from the group in advance so nobody stalls at "what should I build"
- Have a fresh throwaway skill folder ready to build live alongside members
- Time cues: Parts 1 to 3 are 21 minutes total, protect the 30-minute live build, do not let the tour in Part 2 run long
- If the group is slower than expected, cut Step 5 (references file) first, it is the most optional