# Create Asb Skill > Interactive, multi-phase workflow for authoring a new public asb-* skill from one of Jason Cohen's concepts. Invoke explicitly via /create-asb-skill — auto-invocation is disabled to avoid accidentally kicking off this long workflow. - Skill: `asmartbear/create-asb-skill` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add asmartbear/create-asb-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/asmartbear/create-asb-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: asmartbear (https://skillmd.com/u/asmartbear) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/asmartbear/create-asb-skill --- # create-asb-skill — turn a Jason Cohen concept into a public asb-* skill This skill facilitates Jason building a new public skill for [skills.asmartbear.com](https://skills.asmartbear.com). It is **interactive and multi-phase**. Most of the value is in the conversation it forces, not in boilerplate generation. Do not skip phases, do not silently fill in answers, do not race to a draft. This skill is **dev-only**. It freely references other things in this repo (`jason-corpus-search`, `doc-skills`, lint scripts). The skill it *produces*, however, is a public `asb-*` skill and MUST be fully self-contained and Claude-Code-agnostic — see `.claude/skills/CLAUDE.md` for the hard rules. ## Forging vs wielding — keep these straight Two layers of work happen in this skill, and the same words ("adversarial," "artifact") mean different things at each layer. Confusing them produces muddled drafts. Use this vocabulary throughout: - **Forging** = what's happening right now. You and Jason building the new `asb-foobar` skill. The *forger* is you (this LLM session). Jason is the expert being interviewed. - **Wielding** = what will happen later, in some other session, when an end user loads the finished `asb-foobar` skill to apply Jason's framework to their own problem. The *wielder* is that future LLM. The *end user* is whoever installed the skill. | Concept | Forging-time | Wielding-time | | :------ | :----------- | :------------ | | Who's adversarial against whom | **You press Jason** in Phases 2 & 3 to force precision so the produced skill is sharp, not vague. | The wielder presses the end user — when the framework warrants it — to refuse fuzzy inputs and reach a sharp application. Designed in Phase 3, baked in at Phase 4. | | Tone of the pressing | **Short, curt, even rude is fine.** Jason wants you to grill him. "That's vague — sharpen it." "Counterexample, now." No softeners. Bandwidth and time matter more than feelings. | **Tone is gentle. Substance is unyielding.** The wielder is polite in *how* it asks, never in *whether* it accepts a weak answer. It does not let the end user off the hook with vague, wishful, hand-wavy, or "good enough" answers — it stays on the same point, in the same conversation, however many rounds it takes, until the answer is actually sharp. Sharp coach, not drill sergeant — but the coach does not move on until the rep is right. Politeness is in the framing only; the bar does not drop. | | Artifact | The `asb-foobar` skill itself: `.claude/skills/asb-foobar/SKILL.md` plus `src/content/skills/asb-foobar.mdx`. Nothing else. No side-state file. | An *optional* separate markdown file the produced skill MAY tell the wielder to maintain for the end user — ongoing context for a multi-step exercise, often also the final deliverable. Most produced skills won't need one; opt in deliberately during Phase 3. | So when this document says "press hard" in a forging phase, that's YOU pressing JASON. When it talks about "wielding-time adversarial posture" or "a wielding artifact" inside Phase 3 or Phase 4, that's about the produced skill's relationship with its future end user. Use these words explicitly in chat with Jason too — they keep the two layers from blurring. ### How the two files are used at runtime — and why this matters Two files, two completely different jobs. Get this wrong and you'll under- or over-invest in the wrong one. - **`.mdx` wrapper** (`src/content/skills/asb-.mdx`) — this is the **public-facing webpage** on skills.asmartbear.com. The site renders: title (frontmatter) → italic summary (frontmatter) → Installing box → the wrapper body (`## What this is about` with 2–4 paragraphs + `## Example invocation` + `## From the source`). The SKILL.md content is **not** shown on the page; readers get it via the Installing box (download / view-source / raw / copy). So the wrapper body is the *sales surface*: it has to convince a stranger that this is worth installing, give them a vivid example of using it, and point them at Jason's source articles for context. Inviting, concrete, marketing-flavored. - **`SKILL.md`** (`.claude/skills/asb-/SKILL.md`) — this is the **prompt that loads into a wielder LLM** when the end user invokes the skill. The end user never reads it for content (only the LLM does). So it's a tightly-written operational document: framework re-stated in its own words, vocabulary, wielding-time posture and standing rules, how-to steps, refusal conditions. Self-contained, Claude-Code-agnostic. Concretely: do not put marketing prose in SKILL.md, and do not put step-by- step wielder instructions in the .mdx. Long descriptions don't help the wielder LLM (it doesn't load them); standing rules don't help the reader (they're in the wrong voice). ### A "what good looks like" example When unsure of voice, structure, or how the two files complement each other, read the live exemplar pair: - Wrapper: `src/content/skills/asb-rude-qa.mdx` - SKILL.md: `.claude/skills/asb-rude-qa/SKILL.md` The wrapper shows the marketing voice, the `## What this is about` heading with inviting description paragraphs, the `## Example invocation` shape (slash-command fenced block + prose paragraph describing what the skill does without showing literal output), and the `## From the source` foundation-vs- supporting split with why-relevant explanations on every item. The SKILL.md shows wielding-posture rules, the standing dwell/move-on rules, a wielding artifact spec, and refusal conditions. ### Forging-time state — no side file The work product is the state: - The `.mdx` wrapper at `src/content/skills/asb-.mdx` is created at Phase 0 from `template.mdx` and is **kept current through every phase** — references go in as you read them, the summary and long description sharpen as the framework crystallizes. If the session ends mid-stream, the on-disk .mdx already reflects everything decided so far. - The SKILL.md at `.claude/skills/asb-/SKILL.md` is created at Phase 4. From that point on, the on-disk file is the working draft and the resumption point for the SKILL.md side. - Phases 1–3 don't write any SKILL.md yet (decisions accumulate in chat and in the .mdx). Phase 8 polishes both files and lints. If Jason returns and says "continue forging," look for the in-progress SKILL.md on disk, read it, ask which phase he wants to resume at, and proceed. --- ## Phase 0 — Setup Ask Jason for, in this order: 1. **Concept name** (human-readable, e.g. "Acquisition failure diagnostic"). 2. **Skill slug** (must start with `asb-`, kebab-case). Propose one from the concept name; let Jason override. 3. **Source pointers** — the article(s) or chapter(s) where the concept lives. Jason may give article slugs (e.g. `pricing-determines-your-business-model`) or chapter names. Capture as many as he names; these become **Primary references** in the wrapper. ### Then immediately create the .mdx wrapper Copy `.claude/skills/create-asb-skill/template.mdx` → `src/content/skills/asb-.mdx` and fill in what you know now. Write title and summary in the **marketing voice** described below — these are not labels, they're hooks. Don't aim for perfect at Phase 0; aim for "clearly already trying to sell it." Later phases sharpen. - `title:` — full per-page title. Hook + descriptive. See "Marketing voice." - `cardTitle:` — short home-page-card title (1–3 words). Almost always needed because `title` is usually too long for a card. See "Marketing voice." - `hook:` — verb-led one-liner (5–8 words) shown on the home-page card. Distinct from `summary`. See "Marketing voice." - `summary:` — benefit-first one-liner. See "Marketing voice." - `input:` / `output:` — leave the TODO markers; Phase 3 fills these in once the interaction shape is clear. - `related:` — leave commented out for now. Phase 8 (or any later session that adds an adjacent skill) decides whether this skill should point at follow-on skills. - **`## What this is about`** — already present from the template; add one rough sentence of long description under it, led by the reader's payoff, not "this skill does X." Phase 6 expands to 2–4 paragraphs. - **`## Example invocation`** — leave the TODO marker; Phase 3 fills this in once the interaction shape is clear. - **`## From the source`** — record each source Jason named here, as a proper bullet. Foundation (the 1–2 critical sources) goes in the lead paragraph + first bullet list; Supporting (everything else, often empty at Phase 0) goes in the second bullet list. See the "From the source" section near the end of this document for full format. This file is the **live working artifact** for the wrapper-side of the forging — keep it updated continuously (see "Keep the .mdx updated as you go" in the operating principles). Confirm what you wrote back to Jason and move to Phase 1. **Don't** auto-pick the slug without showing Jason. **Don't** start searching the corpus until Phase 1. --- ## Phase 1 — Extract: raw material Goal: gather everything Jason has written that's relevant, in one working mental model, so later phases work from grounded material instead of paraphrase-of-paraphrase. ### Steps 1. **Read the primary sources Jason named.** For each: - Article: `Read /Users/jcohen/Obsidian/Longform/Projects/Articles/Content/.md` - Chapter: start from the chapter index at `/Users/jcohen/Obsidian/Longform/Projects/Hidden Multipliers/Chapters.md` — it lists every chapter with number, title, subtitle, slug, the `Content/.md` body path, and a full section outline. Use it to resolve a chapter name or number to its body file (then `Read` that), to skim the outline before reading, and to spot adjacent chapters worth pulling in. Fallback: `Glob /Users/jcohen/Obsidian/Longform/Projects/Hidden Multipliers/Content/**/*.md`. If Jason named a subsection, grep for the heading. 2. **Semantic search for adjacent material.** Run `jason-corpus-search`'s wrapper with 2–4 different phrasings of the concept: ```sh .claude/skills/jason-corpus-search/search.sh --semantic "" --limit 10 ``` Phrase queries as sentences ("companies that raised prices and survived"), not keywords. The wrapper bakes in the right filters — do not call `cli storage search` directly. Multiple different phrasings surface more than one careful query does. 3. **Just read the hits.** Don't ask Jason which adjacent articles or chapters look worth reading — skim them all. Reading is cheap; asking is friction. Not every word of every hit will be germane, but skim liberally and pick out the parts that are. The only time to ask before reading is if the search returns something that's obviously a different topic with a coincidentally similar title — and even then, lean toward skimming first. 4. **Hold in working memory** (and summarize back to Jason): - **Direct quotes worth preserving** with source attribution. - **Vocabulary** Jason uses for this concept — his actual terms. - **Examples** (companies, scenarios, anti-patterns). - **Adjacent frameworks** he connects this to. - **Open questions** — places where the corpus is fuzzy that Phase 2 will need to press for precision. 5. **Update the .mdx wrapper as you go.** Open `src/content/skills/asb-.mdx` and slot references into `## From the source` as you read them: - The 1–2 most critical articles (the one Jason named as the primary source, plus at most one other that's load-bearing — e.g. the philosophical/conceptual home of the framework) → **Foundation** bullets, each with a one-line why-this-is-critical explanation. - Adjacent articles or chapters that informed specific pieces of the mechanism, the target state, or refusal conditions → **Supporting** bullets, each with a one-line how-it-relates explanation. - URL format: `https://longform.asmartbear.com//` (trailing slash required). Chapters: `*Chapter name* (section "...") in *Hidden Multipliers* — `. - Do NOT append "(A Smart Bear)" after each item — the URL makes the source obvious; the suffix is noise. - Also expand the long description with a rougher-but-fuller version of what the framework is, based on what you've now read. It will get sharpened later; don't aim for tight prose yet. Confirm extraction with Jason before moving on; he may add a source you missed. --- ## Phase 2 — Distill: the framework Goal: a tight, precise statement of the framework. This is where most skills fail — by being vague. ### Draft a four-part statement 1. **Core claim** — in one sentence. What does this framework assert? 2. **When it applies** — what situations trigger it? What signals? 3. **Mechanism** — *why* does it work? What's the causal story? 4. **Vocabulary** — the 2–6 key terms, each defined in one line. Show the draft to Jason. ### Then play devil's advocate — hard Press Jason on every fuzzy edge. Forging-time tone: **short, curt, even rude is fine.** No softeners, no "I just want to make sure I understand," no preamble. Jason explicitly wants the grill. Pick the weakest 2–3 angles for this particular concept and fire them off: - "Give me the simplest counterexample. A case where this framework predicts X but the real outcome is Y." - "What's the boundary? At what point does this stop applying?" - "Two of your terms — [A] and [B] — feel like they could mean the same thing. What's the difference?" - "If a stranger read only this paragraph, what would they get wrong?" - "Where does this conflict with another framework you've written about?" Iterate the four-part statement until Jason signs off. Do not move on while something is "approximately right" — that imprecision compounds in later phases. ### Update the .mdx as the framework sharpens Once the four-part statement is signed off, return to `src/content/skills/asb-.mdx` and **tighten** what's there. Apply the marketing voice (see "Marketing voice" near the end of this document): - `title:` — if the Phase-0 hook now feels off given the sharpened framework, rewrite. Hook + descriptive. - `summary:` — rewrite as a sharp, benefit-first one-liner that reflects the now-precise framework. Lead with the reader's payoff, then the how. - Long description — replace the rough Phase-1 prose with a tighter version. Still 2–4 paragraphs, still benefit-led, now grounded in the distilled vocabulary. --- ## Phase 3 — Operationalize: facilitation design Goal: design what the LLM (loaded with the future SKILL.md) actually *does* with a user. This is the highest-leverage phase. A skill that just recites a framework is a lecture; a skill that facilitates the user applying it is useful. ### Answer these in order, with Jason 1. **Trigger.** What does the user's prompt look like when this skill should auto-load? Write 5 example prompts. Then write 2 prompts that *look* related but should NOT trigger this skill. 2. **Inputs.** What does the LLM need from the user to apply the framework? What questions should it ask first? 2b. **Current-data research — does the wielder assert facts about the outside world?** Some skills have the wielder make claims about real companies, markets, competitors, prices, or other current data (e.g. scanning what customers say about a company, sizing a market, naming who serves a level today, judging whether a trait is rare in the field). For any such skill, bake in a standing rule: the wielder confirms that context using current information from its search/other tools and does NOT rely on internal (training) knowledge, which is stale and is often wrong about a specific, real company or a live market. Word it for the framework — "confirm the company and its market with current search results; do not rely on internal knowledge." Give the fallback for a wielder with no tools (ask the user to paste current data / links; mark the affected outputs low-confidence). Skills that work only from the user's own supplied material (interview answers, beliefs, decisions) do NOT need this — most skills don't. Only opt in when the wielder itself sources outside facts. 3. **Interaction shape — convene the Archetype Council.** Read `.claude/skills/create-asb-skill/archetypes/README.md`. Present the Phase 2 four-part statement to all five personalities (Interrogator, Auditor, Elicitor, Drafter, Decision-Forcer) and render each one's answer in chat, in its own voice, 2–4 sentences: *"If this skill were mine, here is how I'd run it — and here is why I am / am not the right fit."* Include the recusals — Jason sees the whole council. Then declare a verdict: one personality wins, or two blend (name the **primary**, whose skeleton gets copied at Phase 4, and exactly which sections the secondary contributes). Confirm with Jason. If the concept genuinely fits none of the five, say so and design free-form — but treat no-fit as a flag: re-examine the Phase 2 distillation first, since a framework that fits no archetype is often a framework that isn't sharp yet. The remaining questions in this phase (inputs, artifact, posture, output, refusals) fill the chosen skeleton's `TODO(...)` slots — keep your notes keyed to the slot names so Phase 4 is mechanical. 4. **Wielding artifact — does the produced skill need one?** Some skills facilitate a multi-step process for the end user (a diagnostic worksheet, a positioning exercise, a pricing audit) where intermediate state is worth persisting across sessions. If so, the SKILL.md should instruct the wielder to create and update a markdown file at an end- user-chosen path, tracking phase and decisions. Decide explicitly: - Is the process long enough or multi-session enough to warrant a file? - What goes in it? (A YAML header tracking current phase, plus captured decisions.) - Who chooses the path? (End user. If the skill consumes an input file, the output goes in the same directory as the input. When nothing anchors the location — a chain head, pasted inputs — the wielder must ASK where the method's files should live before creating anything, offering the current directory as the default; it never silently picks. And the wrapper documents it: readers are told to name their working directory in the invocation — see the Example-invocation note below.) - Most skills DON'T need a wielding artifact — only opt in when the process genuinely spans sessions or produces a deliverable the end user would want to keep. - **Spec skimmer-zones by exclusion.** If the artifact has a zone meant for human skimming (a top summary), positive adjectives ("brief," "tight," "salient") are not enough — drafts pass them while still editorializing. Name what may NOT appear there (commentary, interpretation, the finding's history, comparisons to prior beliefs) and include a wrong/right example pair. Learned live: a report skill's "as brief as possible" summary shipped lines like "…which cuts against the assumption that tenure dulls the pain." - **Live file, not end-of-session file.** When the artifact is built item by item (a numbered list forged across many exchanges), the wielder creates the file as soon as the FIRST item is settled and appends after each one — long sessions forget and contexts get compacted; the file is the memory, not the chat. The file opens with an explicit `⚠️ IN PROGRESS` status note recording exactly where the walk stopped (plus any plan the resumed session must inherit, e.g. a grouping), so a fresh session can resume from disk alone; finalizing removes the note. This pattern is proven in `asb-interview-hypotheses` / `asb-interview-questions` — copy it, don't reinvent it. Two sibling shapes for other work styles, both proven in the same family: a whole-draft artifact keeps a reviewed-through pointer in its in-progress header (`asb-interview-report`); a skill that edits standing files keeps dated change-log lines per applied change plus one end-of-walk run line, so "log lines but no run line" tells a fresh session a walk died mid-run (`asb-interview-learning`). Whatever the shape: resumable-from-disk-alone is the requirement, and die-and-resume is a mandatory exercise scenario for any skill that keeps state. 4b. **Pacing — one item per exchange.** For any skill that forges multiple items with the user (goals, hypotheses, questions, list entries), bake in strict pacing as a standing posture rule: a SMALL opening move (acknowledge the input, flag anomalies, then start item one — never an opening wall of plans + batched drafts), exactly one item drafted/worked per exchange (candidate variants of the SAME item are fine; drafts for two different items are not), any merge/grouping/skip proposed and confirmed BEFORE acting on it, and a settle-then-write rhythm against the live file. This was learned the hard way: a produced skill that passed prose review and simulation dumped a full plan plus three grilled drafts in its opening message during real use. These skills facilitate the user; a user who can't react to a message is being performed for, not facilitated. Three message-ergonomics rules that live-use keeps re-teaching — bake them into every elicitation-style skill: - **One ask per message.** A message ends with exactly one thing for the user to do — one question, or one draft to confirm; never a question AND a draft AND a second question braided together. Anything the user must respond to is stated in full at the END of the message — never "the questions above" with status text in between — and only what's actually needed is asked (never "answer all four — well, really two"). An observation that wants confirmation says so; don't leave the user guessing what to do with it. This applies to closing/press findings too: work them one at a time, not as a numbered dump of flags. - **Elicitation prompts one at a time.** One prompt per exchange by default; a small choice of prompts only at natural moments (after a skip), framed "answer whichever bites — one is plenty, more is fine; several get worked one at a time." - **Prompt frames are scaffolding, not eligibility.** "Even as a kid…" is an evocative way in; an answer meeting the prompt's spirit counts even when it misses the frame. Follow up for the frame's color as a bonus, never as a gate. 4c. **Ownership vs. craft — who wins a disagreement?** Decide, per part of the produced artifact, which of two hard-bar semantics applies: - **User-owned content** (their beliefs, their decisions): the wielder presses hard but ultimately records the user's version — "it's their list." Candidates offered are templates the user must correct; batch-nodding is refused; but the user's genuine belief goes in even when the wielder disagrees. - **Craft-gated content** (anything with objective quality criteria, e.g. a non-leading interview question): the criteria are NON-negotiable — a violating item is never recorded, in any form, "not even both versions," however the user insists. The refusal is always of the broken item, never of the user's underlying intent, which always has a compliant version available. Naming which semantic governs which section prevents both failure modes: a wielder that overrides the user's beliefs, and a wielder that lets a "it's my interview" appeal breach a quality gate. 5. **Wielding-time adversarial posture.** Critical and frequently underused. Most asb-* skills should not just *apply* the framework — they should facilitate the end user reaching a sharp answer, which usually requires the wielder pushing back. Decide explicitly: - Should the wielder accept the end user's first answer, or press for a sharper one? (Almost always: press.) - Where should it play devil's advocate? (Where the framework's leverage lives — e.g. "are you sure that's really the bottleneck?") - When should it refuse to proceed with vague inputs and demand specifics? - Should it propose a guess and force the end user to defend or revise it? **Tone vs. substance — keep these separate.** The wielder is polite in tone and unyielding in substance. Sharp coach, not drill sergeant — but the coach does not move on until the rep is right. Weak, vague, hand-wavy, or wishful-thinking answers DO NOT pass; the wielder stays on the same point, in the same conversation, however many rounds it takes, until the answer is genuinely sharp. Politeness is in the framing only; the bar does not drop. Concrete moves: - Acknowledge the answer before pushing on it ("I hear that — and here's where it still goes fuzzy:…") instead of "no" or "vague." - Name the *specific* gap, not a general complaint. "What's the timeframe?" beats "be more specific." - Offer a guess or two if the end user is stuck — then ask them to pick or revise. Don't leave them staring at a blank prompt. - Stay on the point until it's actually sharp. Three rounds in is not a reason to accept "good enough." Five rounds in is not either. The wielder moves on when the answer earns it, not when the conversation gets tired. - When the end user gives a wishful-thinking answer ("we'll figure that out later," "it'll probably work"), call it out explicitly and ask them to commit to something concrete now. Bake these into the SKILL.md as standing rules for the wielder — both *what* to press on AND *how* to press, with explicit notice that politeness never lowers the substantive bar. 6. **Output.** What does the user walk away with? A diagnosis? A list? A plan? A revised draft? A persistent artifact file? 7. **Refusal conditions.** When should the LLM say "this framework doesn't apply here"? Concrete cases. ### Devil's advocate on the design - "If I describe my situation badly, will this skill confidently misdiagnose me? Walk me through how it avoids that." - "What's the laziest possible output the LLM could produce while technically following these instructions? Patch that." - "Is the user better off after talking to this skill than after just reading the underlying article? If not, why does the skill exist?" ### Fill in `input:` and `output:` in the .mdx frontmatter Now that the interaction shape is clear, fill in `input:` and `output:` in the .mdx frontmatter — both single-line strings. They render as a two-row "Input / Output" tile above the install box on the per-skill page, giving readers an at-a-glance shape of what the skill consumes and produces. Both must be set for the tile to render; if only one applies, leave both blank. - `input:` — what the user brings. *"A plan, pitch, decision, or positioning — a one-line dilemma or a fully-supported brief."* - `output:` — what the user gets back. *"A markdown document with sharpened decisions, accepted consequences, and the next questions you owe yourself."* Keep them short and concrete; this is a glance-level tile, not prose. ### Fill in the `## Example invocation` section of the .mdx Now that the interaction shape is clear, fill in the `## Example invocation` section of `src/content/skills/asb-.mdx`. Structure: 1. **Lead-in sentence** in second-person voice: "You can invoke the skill like this:" (NOT "A user might invoke" — see the second-person voice rule below). 2. **Fenced code block** with ```text fence (slash commands aren't real code; we just want a clean monospace box). Contents: a realistic slash-command invocation with enough context that the interrogation / diagnosis / coaching has something specific to bite on. Don't make it a one-word toy example. 3. **One or two sentences** saying roughly what happens — the shape of the session and what the reader walks away with. Do NOT narrate the step-by-step process; readers won't read a detailed how-it-works paragraph. Do NOT show literal LLM output. Address the reader as "you." 4. **For skills that write files**, close the section with the standing working-directory note (one short paragraph): tell the reader to say where they're working — name a directory or point at their existing files in the invocation — so the skill keeps the method's files together there, and that it asks before creating anything if they don't. Every published file-writing skill carries this note. --- ## Phase 4 — Draft SKILL.md Goal: write the actual `.claude/skills/asb-/SKILL.md`. From this phase on, the on-disk file is the working draft. Start from the council's winning skeleton, not a blank page: ```sh mkdir -p .claude/skills/asb- cp .claude/skills/create-asb-skill/archetypes/.md .claude/skills/asb-/SKILL.md ``` Then resolve every `TODO(slot-name)` marker using the Phase 1–3 material. The skeleton is scaffolding, not a cage: rewrite freely, rename phases to fit the framework's vocabulary, delete sections that don't apply (e.g. the working-document step when Phase 3 opted out of a wielding artifact). For a blend, import the named sections from the secondary personality's file. Iterate with Edit. **Exit gate:** before leaving this phase, run `grep -n "TODO(" .claude/skills/asb-/SKILL.md` — it must return nothing. Then run `grep -n "Be clear, not clever" .claude/skills/asb-/SKILL.md` — it must return a hit (see Hard-constraint 9); if pruning or a free-form design dropped the block, restore it verbatim before moving on. ### Hard constraints on the draft Follow `doc-skills` for the SKILL.md spec. The constraints below are the ones specific to public asb-* skills (see `.claude/skills/CLAUDE.md`): 1. **Frontmatter is minimal.** Only `description` (universal). NO `allowed-tools`, `model`, `context`, `agent`, `hooks`, `disable-model-invocation`, `user-invocable`, `paths`. Anything Claude Code-specific breaks portability. 2. **Description field**: third person, under 1024 chars, leads with what the skill does, then *when* to load it. Includes the natural language a user would actually say. Double-quoted string (not folded `>`). 3. **No references to anything in this repo.** No mention of other skills, other files, the corpus paths, agents, slash commands. 4. **Re-state, do not copy.** Paraphrase the framework into the skill's own words. No verbatim block quotes from articles or the book. 5. **All nuance baked in.** The future user has no corpus. Every distinction from Phase 2, every refusal condition from Phase 3, every example needed to apply the framework — must be in this file. 6. **Bake in the wielding-time adversarial posture AND tone from Phase 3.** The "How to use this skill" section should give the wielder explicit standing instructions on: (a) **What** to press on — every fuzzy term, every wishful claim, every "we'll figure it out later," every place the framework's leverage lives. (b) **How** to press — gentle in tone, unyielding in substance. Acknowledge before pushing, name the specific gap, offer guesses when the end user is stuck. Sharp coach, not drill sergeant. (c) **When to stop pressing** — only when the answer is genuinely sharp, not when the conversation has gone N rounds. Politeness never lowers the substantive bar; weak, vague, or wishful answers DO NOT pass. Both failure modes ship broken skills: a curt/scolding skill makes the end user feel bad; a polite-reciter skill nods along with sub-standard answers. The wielder helps the end user *earn* a sharp answer. 7. **If Phase 3 opted in to a wielding artifact**, include explicit instructions in SKILL.md for creating, updating, and resuming from that file (YAML header schema, phase tracking, default path). The wielder has no other state. 7b. **If Phase 3 flagged current-data research** (question 2b), bake in the standing rule that the wielder confirms companies, markets, competitors, prices, or other outside facts with current results from its search/other tools and does NOT rely on internal (training) knowledge — with the no-tools fallback. Place it where the wielder actually sources those facts, not as a stray aside. 8. **Body under 500 lines.** Use clear headings. Prose, not bullet soup. 9. **Every skill carries the "Be clear, not clever" block, verbatim.** The archetype skeletons already include it as the final `###` subsection of their posture section; keep it there (or, for a free-form design or a framework with no posture section, place it as a standalone `##` section immediately before "How to use this skill"). The block MUST read exactly: ```markdown ### Be clear, not clever Write to be understood, not admired. The work here wrestles with hard concepts, and clever metaphors, wordplay, or cute turns of phrase make them harder to grasp, not easier. Say plainly what you mean. If a sentence reads more clearly without a flourish, cut the flourish. State the actual point rather than gesturing wittily at it. ``` Do not reword it, do not trim it, do not delete it when pruning skeleton sections. If the skill has no posture/conduct `##` section at all, promote the heading to `## Be clear, not clever` and keep the body verbatim. ### Structure to aim for The archetype skeleton already provides this shape — this block is the reference for what the resolved draft should still look like when you're done rewriting: ``` --- description: "..." --- # ## ... ## ... ## ... ### Be clear, not clever ## How to use this skill When the user describes : 1. 2. 3. 4. ``` After drafting, read your own draft cold and ask: "If this were the only thing I had, could I apply the framework?" Mark gaps. Patch. Then go to Phase 5. --- ## Phase 5 — Source-map faithfulness audit Goal: prove every load-bearing claim in the draft is grounded in Jason's actual writing or an explicit forging-time decision — BEFORE adversarial review, so review critiques a faithful draft rather than polishing an invented one. This is the defense against the forger's paraphrase quietly becoming the published framework. ### Steps 1. **Build the source map in chat** (not a committed file). One row per H2/H3 section of the draft, and per distinct claim within it: ```
→ ``` Grounding is exactly one of: - **(a) Source passage** — article slug or chapter name plus a few identifying words of the passage ("strategic-choices — 'both sides are smart'"). - **(b) Forging decision** — "Phase 2/3 conversation — Jason confirmed ". For things Jason decided during forging that aren't in the corpus. - **(c) UNGROUNDED** — neither. Flag it. 2. **Re-open sources as needed.** Read the corpus files again; re-run `jason-corpus-search` for claims you can't place. Do NOT ground from memory — memory of the corpus is exactly where drift hides. 3. **Patch the three failure classes:** - **Ungrounded** — the forger invented it. Show it to Jason: either he explicitly signs off (it becomes class b) or it gets cut. - **Contradiction** — the draft asserts X where the source says Y. Show Jason both, side by side. Fix the draft — or, if Jason is deliberately departing from his own published take, record that decision out loud (it becomes class b, with the departure named). - **Drift** — a paraphrase that changed the meaning, scope, or strength of the original ("usually" became "always"; a two-condition rule lost a condition). Tighten the draft to match the source. **Drift runs in both directions**: check for rules STRICTER than the source, not just weaker. (Real case: a draft banned all willingness-to-pay hypotheses as "purchase referendums" when Jason's canonical example list explicitly contains "will pay $50/mo" hypotheses — the source bans asking "would you buy?", not holding priced beliefs. Over-restriction is invented doctrine, just as much as over-loosening.) 4. **Show Jason the summary**: counts per grounding class, plus every flag and how it was resolved. His sign-off gates Phase 6. --- ## Phase 6 — Adversarial review Goal: stress-test the draft before it ships. Be hostile to your own work. Run these tests; patch the on-disk SKILL.md after each: 1. **Description targeting.** Write 8 plausible user prompts: 4 that SHOULD trigger this skill, 4 that look similar but should NOT. For each, predict whether a model reading just the description (no body) would load this skill. Any miss = revise the description. 2. **Cold read.** Re-read the draft body as if you had never seen the corpus. List every place you'd be confused, every term you'd guess at, every step where you wouldn't know what to do. Patch all of them. 3. **Adversarial user.** Imagine a user who describes their situation ambiguously or in a way that *looks* like a match but isn't. Walk through the skill. Does it confidently misapply? If yes, strengthen refusal conditions or add a clarifying-question step. 4. **Wielding-posture audit (both directions).** Two failure modes to check: - **Too soft:** does the draft let the wielder accept the end user's first vague answer? Does it walk through the framework politely without pressing? If yes, patch in tenacious follow-up — name the specific gap, refuse weak inputs, propose-and-defend. - **Too harsh:** does the draft instruct or license the wielder to be curt, dismissive, or scolding toward the end user? Forging-time grilling tone is for you-and-Jason only. Wielding tone is gentle-but-forceful — sharp coach, not drill sergeant. Acknowledge before pushing, offer guesses when the end user is stuck, never make them feel bad. Both failure modes ship broken skills. Patch wherever the balance is off. 5. **Portability scan.** Grep the draft for Claude-Code-isms: `$ARGUMENTS`, `allowed-tools`, `context:`, `subagent`, `slash command`, `/`-commands, references to this repo. Any hit = remove or rewrite. Show Jason the post-review diff and get sign-off. --- ## Phase 7 — Simulated use Goal: watch the draft skill actually being wielded before it ships. Prose review (Phases 5–6) catches textual failures; only simulated use catches behavioral ones — a wielder that recites instead of applies, nods along with weak answers, or forgets to refuse. Follow the procedure in `.claude/skills/exercise-asb-skill/SKILL.md` against the on-disk draft: 1. Quarantine: the wielder side of each role-play uses ONLY the draft file. 2. 3–5 scenarios, required mix: canonical user, terse/underspecified user, boundary case, refusal case (optionally a lazy answerer). Show the list to Jason before running. 3. Run labeled transcripts; judge each against the fixed rubric (applied vs. recited, specific vs. generic, dwell fired, refusal fired, tone/substance split, artifact handling). 4. Patch the draft for every FAIL/ …(truncated)