Building an Effective Skill — preston-writing as the Case Study

1. The Job — Voice Discipline That Travels

Preston's voice has observable patterns. The opening leads with a concrete fact. Numbers go bare, with "for context" as the signature for benchmarks. Pronouns favor "we" for organizational actions, "I" for personal reflection. Only people are active subjects. Forbidden constructions ("X, not Y" / "not X, but Y" / "isn't X — it's Y") stay out. Forbidden words (unlock, leverage, navigate, foster, robust, holistic) stay out.

Encoded as a Stage 1 Prompt, those rules would fit one drafter and one recurring task. Encoded as a Stage 2 Skill, they travel — fpa-storyteller loads them inside financial_modeling to produce Big Idea sentences; a grant writer loads them via funder-framing chaining; Preston himself loads them when drafting a LinkedIn post. Same SKILL.md. Different hosts. Same voice out the other side.

2. Folder Anatomy — What Lives at ~/Desktop/BRAIN/skills/skills/preston-writing/

The skill is one folder. The structure is the canonical layout for any Anthropic-style skill. Three top-level pieces, each with one job.

The directions live in SKILL.md + the three guides in reference/ (voice, email, anti-AI). The examples live in the eleven sample writing files — actual published artifacts the skill points at when Claude needs to see what the voice looks like in practice. That is the second discipline an effective skill encodes: it carries both the rules and the place to go for the examples that ground them.

3. The Frontmatter — The Description Is the Trigger

The frontmatter is the always-in-context surface. Claude reads name and description from every available skill and decides which to consult. preston-writing's actual frontmatter, verbatim from the file:

From SKILL.md — frontmatter
---
name: preston-writing
description: >
  Preston Magouirk's writing voice, style, and anti-AI rules for all content creation.
  Use this skill whenever drafting, editing, or reviewing any written content — LinkedIn posts,
  grant narratives, board materials, thought leadership, policy briefs, blog posts, conference
  remarks, donor communications, emails, or any deliverable that will carry Preston's name or
  voice. Also use when the user asks to "write like me," "match my voice," "review for tone,"
  or wants to ensure content doesn't sound AI-generated. Trigger on any content creation,
  deliverable drafting, writing review, or voice-matching task.
metadata:
  author: Preston Magouirk
  version: 2.6.0
---

That description runs about 100 words. Every additional sentence names a real surface — LinkedIn posts, grant narratives, board materials, thought leadership — and a real user phrase — "write like me," "match my voice," "review for tone." The description is pushy on purpose. Skills under-trigger; pushiness is the corrective.

The skill-creator skill (Anthropic-authored) ships with a description-optimization loop that runs eval queries against held-out tests to score trigger rates. For a Stage 2 skill the team will use weekly, running the loop once per major refresh is worth the half-hour.

4. The Body — Where the Rules Live

The body of SKILL.md carries the directions. preston-writing's body organizes into sections built around observable behaviors with example pairs. A few real headings from the file:

• Voice DNA. Concrete behaviors extracted from real published writing. How Preston opens. How Preston closes. Pronouns. Agency rule. How Preston handles data. How Preston acknowledges failure. How Preston qualifies success.
• Agency Rule — Only People Can Be Active Subjects. "Clarity drives execution" gets rewritten as "Teams execute better when they're clear on the plan." The rule is checkable — if the subject of the sentence is a noun you couldn't shake hands with, rewrite it.
• Forbidden Words and Forbidden Constructions. Lists the AI-tell words and the antithesis shapes that get caught and rewritten. The rule names them so grep can find them before commit.
• How Preston Handles Data. "75-95% of scholars earned their degrees. For context, about 37% of D.C. students who enter college earn a degree within six years." Bare number, "for context," then comparison.

Each section pairs a rule with a real example pulled from the reference folder. The skill body is short on theory and long on observable behavior. That is what makes it usable by other agents.

From SKILL.md body (real excerpt)### How Preston Opens

Lead with a concrete fact, outcome, or situation.
Never a question, never a sweeping claim, never a quote, never
throat-clearing.

| Preston opens like this | Not like this |
|---|---|
| "DC CAP had a breakthrough year in 2025." | "In today's rapidly changing education landscape..." |
| "For the first time since 1999, Congress raised the DC Tuition Assistance Grant." | "What if I told you that a single policy change..." |
| "I've been experimenting with AI tools since ChatGPT launched, like most people in knowledge work." | "As someone who is passionate about leveraging technology..." |

Within 1-2 sentences, ground the reader — who,
where, what scale.

The "right vs wrong" table is the discipline. Each row is grounded in a real Preston-published opening. The model loading this skill has both the rule and the example.

4.5. What v2.6 Added — Three Disciplines That Sharpen the Skill

Three improvements landed in v2.6. Each one addresses a real way a Stage 2 skill can fail under load: drift between rule and evidence, friction for mid-task agents, and ambiguous sample selection. The fixes are observable on disk.

1. Fast Path routing table — for mid-task agents

A Stage 2 skill is read by other agents at runtime, not by humans during onboarding. When fpa-storyteller triggers preston-writing mid-task to draft a Big Idea sentence, scanning a 300-line voice essay first is the wrong shape. v2.6 adds a routing table at the top of SKILL.md — eleven deliverable types, the sample(s) to load for each, and the voice register. The agent reads four lines and lands on the right sample.

From SKILL.md (v2.6) — Fast Path routing table, top of file## Fast Path — Pick the Sample Before You Draft

Apply Voice DNA + Anti-AI Rules first. Then load the sample(s) closest to the deliverable.

| Deliverable | Sample(s) to load | Register |
|---|---|---|
| LinkedIn / thought leadership | sample_writing_five_lessons.txt (voice anchor) + sample_linkedin_dctag_final.md (close pattern) | Leadership Reflection |
| Grant narrative / case for support | sample_case_dc_cap_scholarly.md (Feb 2026 scholarly case) | External Research + Internal Strategy |
| Policy brief (op-ed style) | sample_brief_brookings_directadmissions.md | External Research |
| Academic paper — college access | sample_paper_nonsubmitters.md (Odle + Magouirk, 2023) | External Research |
| Academic paper — early childhood | sample_paper_qris_louisiana.md (Bassok + Magouirk, 2021) | External Research |
| Email | email_style_guide.md (skip Voice DNA, go directly) | Leadership Reflection |
[...]

The table is the fast path; the deep Voice DNA is still there for any agent that needs it. Progressive disclosure on a single page.

2. Evidence trailers — every rule traces to a sample line

Before v2.6, the Voice DNA section said "These patterns were extracted from Preston's actual writing" without naming which sample proved which pattern. A reader could not verify a rule, and a future editor could not tell whether updating a sample would invalidate a rule. v2.6 adds an Evidence: trailer under every Voice DNA subsection that cites the specific file and quote.

From SKILL.md (v2.6) — How Preston Closes, with new Evidence trailer### How Preston Closes

Close with a conditional invitation that positions the writer as a learner.

Pattern: "If you [share this context], I'd [welcome/love to hear/encourage]..."

| Preston closes like this | Not like this |
|---|---|
| "Please let me know what you learned this year." | "The future of education depends on all of us." |
| "If you work with DC students or families navigating college costs, I'd welcome hearing how this changes the conversation." | "Together, we can transform outcomes for every student." |

Evidence: sample_writing_five_lessons.txt final line — "Please let me know what you learned this year. I'm always looking to improve our internal models..." sample_linkedin_dctag_final.md final line — "If you work with DC students or families navigating college costs, I'd welcome hearing how this changes the conversation."

Every Voice DNA section now carries one of these. The rule says what to do; the evidence trailer names the sample and the quote that proves the rule is grounded, not invented. If a sample is removed or updated, the affected rules surface immediately.

3. Sharpened "when to read" — sample cluster differentiated by topic and structure

Before v2.6, the Reference Files table at the bottom of SKILL.md listed two academic papers both labeled "Academic writing" and three policy/research briefs labeled with overlapping types. An agent picking a sample had to open all three to choose. v2.6 distinguishes each one by topic, authorship, structure, and the audience it was written for.

From SKILL.md (v2.6) — Reference Files table, sharpened| File | Type & Topic | When to read |
|---|---|---|
| sample_paper_nonsubmitters.md | EdWorkingPaper 23-819 — college application non-submitters across 1.2M students (Odle + Magouirk, 2023) | Peer-review academic writing on college access, application equity, K-12-to-college pipeline. Use for the abstract + fixed-effects + discussion structure. |
| sample_paper_qris_louisiana.md | AERA Open, 2021 — statewide early-childhood quality improvement in Louisiana (Bassok + Magouirk + Markowitz) | Peer-review academic writing on early childhood / pre-K / program quality systems. Use when the topic is early childhood, not college access. |
| sample_brief_brookings_directadmissions.md | Brookings article, Oct 2023 — direct-admissions policy reform (Odle, Delaney, Magouirk) | Mainstream-press policy briefs, op-ed-style commentary on college access reform. |
| sample_report_test_optional.md | Common App data report, Sept 2021 — test-optional admissions trends during COVID | Practitioner-audience data reports with "findings + chart + implications" structure aimed at counselors and partner institutions. |
| sample_report_early_admission.md | Common App data report, July 2023 — Early Decision / Early Action timing trends | Practitioner-audience data reports where Preston is the corresponding author. Use for longer report format with multiple findings sections. |

One more change: voice_style_guide.md was slimmed. It used to duplicate the registers, the matrix, and the writing rules already in SKILL.md. v2.6 reduces it to its unique contributions — DC CAP framing language (impact phrases, problem framing, approach framing), extended "not X, it's Y" rewrites, and sample-governance conventions. One source of truth per rule.

5. The Reference Folder — Where the Skill Sends Claude for Examples

This is the part most skills under-build. The body of SKILL.md names the rules; the reference folder carries the source material. preston-writing's reference/ folder holds three style guides plus eleven actual writing samples — published essays, LinkedIn posts with version arcs, briefs, papers, reports.

When fpa-storyteller is drafting a Big Idea sentence and needs to see what Preston's "How Preston Closes" pattern actually looks like, it does not generate from training memory. The body of SKILL.md directs it to reference/sample_writing_five_lessons.txt (the canonical voice sample, the published essay) or to reference/sample_linkedin_dctag_final.md (the LinkedIn close pattern in published form). The model reads the real artifact, then writes.

What goes in each reference type

• Style guides (voice_style_guide.md, email_style_guide.md, anti_ai_rules.md): each one owns a non-overlapping slice. voice_style_guide.md (slimmed in v2.6) holds only DC CAP framing language and sample-governance conventions. email_style_guide.md holds email-specific anatomy, tone dials, and templates. anti_ai_rules.md holds the forbidden phrase and vocabulary tables. Loaded when the body needs to go deeper than the SKILL.md summary.
• Source map (source_paths.yml): a YAML file that tells the skill where to find external source materials. Keeps the rest of the references portable.
• Writing samples (eleven files): real artifacts Preston published. The voice is observable in them. The skill quotes from them when explaining a rule and points to them when Claude needs to see the rule in practice.
• Version-arc samples (sample_linkedin_dctag_versions.md): one piece across multiple drafts. Shows the voice rules being applied through the drafting trace. End-state samples alone would hide the iteration.

6. How fpa-storyteller Loads It Inside financial_modeling

The financial_modeling orchestration has eleven agents. One of them, fpa-storyteller, is the narrative lane. Its agent file at .claude/agents/fpa-storyteller.md declares which skills it loads at session start.

From .claude/agents/fpa-storyteller.md — Skill Specification (Framework §1.4)The storyteller applies these specific disciplines:

[...]

8. Preston writing standards per `preston-writing` BRAIN skill: lead with the
   point, active voice, no AI markers, no em-dashes, no forbidden constructions,
   no equity language.
9. DC CAP org-intelligence per `dc-cap-org-intelligence` BRAIN skill: verified
   numbers, narrative arc, audience-specific framing rules.

[...]

BRAIN skills:
- preston-writing — voice
- dc-cap-org-intelligence — verified facts and framing
- executive-summary-formatter — board memo structure
- funder-framing — funder-type-specific voice

The agent declares the skill by name. At runtime, the description matches the storyteller's task, and the SKILL.md body loads. The body directs the agent to the references it needs (the voice guide, the anti-AI rules, the sample essay). Same SKILL.md. Different host. The voice carries.

The same preston-writing skill loads inside other agents and surfaces — anywhere a Preston-voice draft is being produced. It is the canonical Stage 2 build: one expertise pattern, many consumers, one place to update when the voice evolves.

7. What Makes a Skill Effective — The Discipline preston-writing Encodes

• The description is pushy and specific. Names the surfaces (LinkedIn, grant narratives, board materials). Names the user phrases ("write like me," "match my voice"). Skills under-trigger; pushy descriptions are the cure.
• The body carries observable behaviors with example pairs. "Lead with a concrete fact" plus three real opening examples beats "use a strong hook" every time. The rules are scannable; the examples are grounded.
• The reference folder carries the source material. The body says what the rule is; the reference folder shows what the rule looks like in published work. Real writing samples are the corpus that gives the agent its "intuition."
• Forbidden lists are explicit. Forbidden words, forbidden constructions, forbidden opening shapes. Each one is grep-able. The skill catches violations because the violations are named.
• The skill is versioned. version: 2.5.0 in the frontmatter; learnings.md tracks what changed. Skills evolve; the versioning is the discipline that keeps the evolution legible.
• The skill carries one expertise area. preston-writing handles voice. It does not handle financial benchmarks (that is dc-cap-org-intelligence) or funder-type framing (that is funder-framing). Each skill stays in its lane; consumers chain the ones they need.

8. When to Promote — Signals Stage 2 Has Outgrown Itself

A Skill is the right container while the work is one expertise pattern that travels across hosts. The signals to promote — to Stage 3 (a Project that wraps a full workflow) — are concrete:

• The workflow needs files Claude must read at conversation start, regardless of task language. If every conversation should also load the FY27 raise targets and the named-donor schedule, that is a Project's job — files load automatically at conversation start rather than waiting for a trigger.
• The team needs persistent context across many conversations. A Skill loads, answers, exits. A Project keeps the same instructions and files in place across every conversation inside it.
• Governance needs a first-class home. A Skill carries escalation hints in its body. A Project carries data tier, restricted topics, escalation path, and audit cadence as first-class config.
• Multiple skills need to chain in a stable order. preston-writing + dc-cap-org-intelligence + executive-summary-formatter chain inside fpa-storyteller at Stage 4. If a Stage 3 Project could wrap the same chain for a smaller audience, that is the next rung up.

Artifact C walks the Stage 3 Project move using financial_modeling itself as the thought experiment.