# Building Claude Code Skills by Conversation: The Dossier Pattern > [!tip] TLDR > A frustration ("everyone keeps asking me 'have you seen this AI company?'") became a 30-minute brainstorm with Claude that produced a working skill, a test run on a real company, a critique cycle, a rename, and a publish to GitHub. The skill is [dossier](https://github.com/BioInfo/rundatarun/tree/main/skills/dossier) in [rundatarun](https://github.com/BioInfo/rundatarun). The pattern that produced it is reusable: the conversation is the spec. > > **Copy-paste prompt for Claude Code, Codex, or any AI assistant:** > > ``` > Brainstorm a Claude Code skill with me. I keep needing to do <recurring task>. I solved it manually once by <what worked> and got <specific output>. Now I want it on tap. Do NOT write code yet. Ask me clarifying questions about scope, output shape, voice, where output should land, and how the skill should behave on edge cases. After my answers, propose a name, then we'll run a manual test on the original case before codifying. Reference: https://github.com/BioInfo/rundatarun/tree/main/skills/dossier for the shape of the eventual artifact. > ``` > > Read on if you want to understand how this works and why the test-before-codify rhythm matters. <div class="topic-area"> ## The frustration Every senior practitioner in AI gets the same question on rotation: *"Have you seen `<company>`?"* It comes from your boss, from a coworker, from inbound LinkedIn, from a press release someone forwarded. The answer everyone wants from you is not "yes, I've heard of them." The answer is *should we care*. The standard workflow for getting to *should we care* is broken in a predictable way: 1. Visit the company website. Marketing fluff. "Power enterprise decisions with AI that works." Says nothing. 2. Ask a general LLM. You get a Wikipedia-grade summary with no opinion. 3. Spend 20 minutes digging through founder interviews, case studies, and Hacker News comments to find substance. 4. Realize you still don't know whether the company is better or worse than the obvious alternatives for *your* specific use case. Fractal Analytics was the company that broke me. I'd been invited to one of their private events. Their site was useless. I asked Gemini what they actually do, got a generic answer, then fed Gemini my actual context (incoming role, what I already have, what I'm building) and watched it produce something tailored. Fractal is good *if* you have these conditions. Here are three alternatives that cover gaps Fractal won't. Suddenly the meeting prep wrote itself. That tailored, comparative output is what I wanted on tap. So I opened Claude Code and started a brainstorm. This is the same conversational rhythm I've used to build other skills covered in [[AI Development & Agents/claude-code-best-practices|Claude Code: Best Practices for Agentic Coding]] — the difference is the explicit Q&A-before-code step, which is what makes the resulting skill tight rather than sprawling. </div> <div class="topic-area"> ## The conversation as spec The prompt I started with (paraphrased): > *"I often hear of cool companies. Fractal.ai for instance, but their website is marketing fluff. I want to know what value they actually bring. I dug in with Gemini, fed it my context, and got something insightful: tailored alternatives based on what I have and what I need. I'm always asked 'have you seen this company?' I want an easy way to cut through the BS. Could pair with last30days, drop the output in my vault. Brainstorm this with me. Is there stuff already out there to steal from? What do you think? Ultrathink with me, ask questions, brainstorm."* Three things in that prompt do most of the work: 1. **Names the frustration with a specific example.** Fractal Analytics, not "AI companies in general." Specifics force specifics. 2. **Names what worked when solving it manually.** Gemini, context injection, tailored alternatives. That's the shape of the eventual skill, given away in the opener. 3. **Invites brainstorming explicitly.** Not "build it" or "give me the spec." *"Brainstorm with me, ask questions."* That's permission to slow down and disambiguate before writing code. The fourth thing that matters is what's *not* in the prompt: a name, a tool list, an output format, a directory structure. Those are decisions to be earned in the conversation, not pre-loaded. </div> <div class="topic-area"> ## The seven questions that became the spec Claude's response wasn't code. It was a list of existing tools to potentially steal from (commercial intelligence platforms, YC's company-page format, founder podcast appearances, GitHub orgs as ground truth), then seven open questions: 1. **Always comparative, or sometimes just decode?** Single-company writeup vs forced 3-alternative shortlist. 2. **Vault auto-injection or inline context?** Pull role / projects / adjacent capabilities from a known location vs feed them each time. 3. **Refresh old files or version them?** When a company comes up again 6 months later. 4. **"Who to talk to" output?** Should the skill identify a specific contact or founder to reach out to? 5. **AI companies only, or anything?** Scope question. 6. **Pair with `last30days` at the trigger, or as a follow-up?** Cost vs convenience trade. 7. **Voice register: skeptical-analyst or neutral-briefing?** Tone calibration. My answers, one line each: 1. Always compare. 2. Auto-inject vault context, ask inline if missing. 3. Refresh in place. 4. No contact identification. 5. AI only. Do one thing well first. 6. Follow-up only. 7. Skeptical, but not over-indexed on skeptical. Those seven Q&A pairs became the skill's design contract. Every line of the eventual SKILL.md traces back to one of those answers. No backtracking, no scope creep, no extra features. This is the part of skill-building that gets skipped most often. People write the skill body first, then iterate on the description, then realize the description doesn't match the body. Inverting that, getting the design contract right *before* the body, is what makes the final artifact tight. </div> <div class="topic-area"> ## Test on a real company before codifying Before turning the design into a skill, I ran it manually on the actual triggering case: Fractal Analytics. Claude ran the research workflow inline (parallel `WebFetch` + `WebSearch` + vault search) and produced the dossier directly to my vault. Reading the output side by side with what Gemini had given me on the same question surfaced things I would have missed otherwise: - **Vault context is the differentiator.** Gemini gave me generic alternatives. Claude pulled my actual project notes ("you already have something like this at X") and wrote the comparison against my real adjacent work. That's the value-add a general LLM can't reproduce because it can't read your vault. - **The sharp opener question is the highest-value output.** One question, calibrated to expose the marketing-vs-buyer gap in 90 seconds. The dossier's other 1,200 words exist to *support* that question. Frame the output around the question, not around the company description. - **A vertical-native competitor I almost missed.** Spending 8 minutes on substance search surfaced ZS Associates' Max.AI (low-code agent platform) and Trials.ai (clinical trial design agent). Both products change the comparison materially. Generic research at speed missed them. Critique is easier when there's an artifact to critique. Building the artifact *before* finalizing the skill design caught things that would have been awkward to retrofit. </div> <div class="topic-area"> ## The refinement cycle After reading the output, I gave Claude one note: *"I want a directory per company, not a single file. I'll track contacts and meeting notes alongside."* That changed the output convention from `Companies/<slug>.md` to `Companies/<slug>/dossier.md`, with sibling files reserved for the human (contacts, meeting notes, artifacts). The skill picked up the constraint that it should only ever write `dossier.md` and treat the sibling files as read-only. Small change, large downstream effect. Six months from now when I drop a deck someone sent me into `Companies/<slug>/artifacts/`, the skill won't blow it away on the next refresh. The lesson: structural feedback after the test run is more valuable than structural feedback before it. You can't anticipate the working notes you'll want to keep alongside the AI-generated brief until you've seen the AI-generated brief once. </div> <div class="topic-area"> ## Naming and shipping Working title: *Company Landscaper*. Functional, ugly. I asked Claude to suggest something sharper. Three options came back: `/dossier` (what the output is), `/decode` (what the action is), `/recon` (military intelligence flavor, fits the pre-meeting use case). Picked `/dossier` because it's the noun that already describes the artifact and reads cleanly in the vault path. Then scaffold. SKILL.md frontmatter, trigger phrases, the seven Q&A pairs translated into workflow steps, the 3+1 alternatives rule made explicit, the per-company directory contract codified. Symlinked from `~/.claude/skills/dossier`. Live on the next session start. Total elapsed from initial prompt to working skill: 30 minutes. Most of that was reading the Fractal output and noticing what was missing. </div> <div class="topic-area"> ## The repeatable pattern If you want to brainstorm a skill with Claude this way, the shape is: 1. **Open with a specific frustration and a worked-it-manually example.** *"I keep needing X. I solved it once by doing Y, and Z worked. Now I want it on tap. Brainstorm with me, don't build yet."* The worked example is doing 80% of the spec work for you. 2. **Let Claude ask questions before you let it write code.** If the first response is code, push back. If the first response is a question list, answer them carefully. The questions you don't see are the ones Claude is going to guess on later. 3. **Test on the original triggering case before codifying.** Run the workflow manually inline. Compare the output to whatever you used to solve the problem before (Gemini, a colleague, a manual process). See what's actually different. That comparison is where the skill earns its keep. 4. **Take one structural critique after the test.** Don't iterate on micro-wording. Iterate on the data shape, the directory structure, the trigger calibration. Big bones, not finishes. 5. **Name last.** The right name surfaces once you know what the artifact actually is. 6. **Ship to the place you'll actually use it.** A skill that lives in your local Claude Code config but not in any repo is one machine wipe from gone. Add it to a versioned repo (public or private) on day one. </div> <div class="topic-area"> ## What's in the repo The skill is in [rundatarun](https://github.com/BioInfo/rundatarun) under [`skills/dossier`](https://github.com/BioInfo/rundatarun/tree/main/skills/dossier). It includes: - `SKILL.md`: the Claude-facing file with the full workflow and trigger phrases. - `HOW-TO.md`: the human-facing setup walkthrough, including the optional enhancements (self-hosted firecrawl MCP for better scraping, semantic vault search for richer context). - A [worked example](https://github.com/BioInfo/rundatarun/blob/main/examples/dossier/fractal-analytics-walkthrough.md) showing a real run against Fractal Analytics, sanitized for public consumption. Drop the skill in `~/.claude/skills/`, and the next time someone asks you *"Have you seen `<AI company>`?"* the answer will be a vault-ready briefing, three alternatives, and a question calibrated to expose the gap in 90 seconds. The next skill in queue uses the same brainstorming pattern. So does the one after that. The shape generalizes because skill creation is, fundamentally, an exercise in disambiguating a recurring frustration into a fixed-shape workflow. The conversation is the spec; the SKILL.md is the codification. The Q&A-before-code rhythm is the part most people skip. If you want to see this pattern applied to a different problem domain, look at how I built out [[autonomous-ai-agent-squad-10-dollars-month|the autonomous agent squad]] — same conversational disambiguation, different artifact. The constant is the rhythm: name the frustration, name what worked manually, refuse to write code until the questions are answered, test before codifying. Try it on your next recurring annoyance. </div>