@opendirectory.dev/skills 0.1.0

package/skills/noise2blog/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: noise2blog
+description: Turns rough notes, bullet points, voice transcripts, or tweet dumps into a polished, publication-ready blog post. Optionally enriches with Tavily research to add supporting data and credibility to claims. Use when asked to write a blog post from notes, turn rough ideas into an article, expand bullet points into a full post, clean up a voice transcript into a blog, or repurpose a tweet thread as an article. Trigger when a user says "write a blog post from this", "turn these notes into a post", "expand this into an article", "make this publishable", "I have rough notes write a blog", or "clean up this transcript".
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# Noise to Blog
+
+Take any rough input (bullet points, voice transcripts, tweet dumps, or short drafts) and produce a polished, publication-ready blog post. Every claim traces to the source material or Tavily-verified research.
+
+---
+
+**Critical rule:** DO NOT INVENT SPECIFICS. Every claim, metric, and example in the blog post must come from the raw input or a Tavily search result. Never fabricate data, quotes, or outcomes.
+
+---
+
+## Step 1: Setup Check
+
+Confirm required env vars are set:
+
+```bash
+echo "GEMINI_API_KEY: ${GEMINI_API_KEY:+set}"
+echo "TAVILY_API_KEY: ${TAVILY_API_KEY:-not set, Tavily enrichment will be skipped}"
+```
+
+**If GEMINI_API_KEY is missing:**
+Stop. Tell the user: "GEMINI_API_KEY is required. Get it at aistudio.google.com → Get API key. Add it to your .env file."
+
+**If TAVILY_API_KEY is missing:**
+Continue. Note that Tavily enrichment will be skipped. The blog post will be based entirely on the provided content. This is fine for personal stories, tutorials from experience, or opinion pieces.
+
+**Confirm input is present.**
+The user must provide one of:
+- Pasted text (bullet points, rough notes, transcript, tweet dump, short draft)
+- A URL to fetch
+
+If no input, ask: "Share your rough notes, bullet points, or transcript. Paste them directly, or give me a URL to fetch the source."
+
+---
+
+## Step 2: Read and Analyze Input
+
+**If input is a URL:**
+Fetch the page content using WebFetch. Extract: title, author, publish date, all body text, key statistics, numbered lists, subheadings, quotes.
+
+**If input is pasted text:**
+Read it directly. Identify the input type:
+- **Bullet points or rough notes**: fragmented ideas, incomplete sentences, stream of consciousness
+- **Voice transcript**: conversational, repetitive, filler words (um, uh, like, you know), meandering sentences
+- **Tweet thread dump**: short fragments, @mentions, hashtags, "1/8" numbering
+- **Short draft**: structured but thin, needs expansion and polish
+
+**QA checkpoint:** State before continuing:
+1. Input type detected
+2. Core thesis or main argument in one sentence
+3. The 3-5 strongest insights, facts, or ideas from the raw content
+4. Any claims that need external verification (benchmarks, statistics, product comparisons, research findings)
+
+If you cannot identify a core thesis, ask: "What's the single most important thing you want readers to take away from this?"
+
+---
+
+## Step 3: Choose Blog Post Style
+
+Four styles. Auto-detect from content signals. User override always respected.
+
+| Style | When to use | Signals |
+|-------|-------------|---------|
+| Technical Tutorial | Step-by-step guide, how-to, code walkthrough | Numbered steps, commands, code snippets, "how to" in content |
+| Case Study | Before/after story, build log, lessons learned | Specific results, timelines, first-person journey |
+| Thought Leadership | Opinion, argument, counterintuitive claim | "I think", "the problem with X", contrarian position, debate framing |
+| Explainer | What is X, why it matters, how it works | Concept-first, comparison-heavy, "most people don't know" |
+
+**Detection logic:**
+- Content has numbered steps or commands → Technical Tutorial
+- Content has before/after, specific metrics, or narrative arc → Case Study
+- Content argues against common wisdom or makes a strong opinion claim → Thought Leadership
+- Content explains a concept, tool, or trend for people unfamiliar with it → Explainer
+
+State chosen style and reasoning. If ambiguous, pick one and note the choice.
+
+---
+
+## Step 4: Enrich with Tavily Research
+
+Skip this step silently if TAVILY_API_KEY is not set.
+
+Search for supporting evidence for claims in the raw content that could benefit from verification or data. Good candidates:
+- Product benchmarks or performance numbers
+- Market statistics or industry trends
+- Technical comparisons ("X is faster than Y")
+- Any number the user mentioned from memory rather than a cited source
+
+Run one Tavily search per claim that needs verification. Limit to 3 searches maximum to avoid over-sourcing:
+
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "SPECIFIC_CLAIM_OR_TOPIC",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+Keep results with `score >= 0.65`. Extract: title, url, content snippet.
+
+**Rules for using Tavily results:**
+- Use them to support or verify claims already present in the raw input. Never introduce entirely new claims from search results.
+- Attribute sources naturally in the text: "according to [Source]", "data from [X] shows"
+- If no Tavily result confirms a claim, leave the claim unverified rather than substituting an unrelated result
+
+---
+
+## Step 5: Generate the Blog Post
+
+Read `references/blog-format.md` in full. Select the matching template from `references/output-template.md`. Internalize all rules before generating.
+
+Write the Gemini request to a temp file to handle special characters safely:
+
+```bash
+cat > /tmp/noise2blog-request.json << 'ENDJSON'
+{
+  "system_instruction": {
+    "parts": [{
+      "text": "You are a tech writer who sounds like a real person. Rules: Active voice only. Short paragraphs, 1-3 lines max, then a blank line. Use contractions naturally (don't, won't, it's, can't, you're, they're). No em dashes — use a comma or period instead. No semicolons. Every sentence needs a concrete detail: a number, a tool name, a file name, a command, a result. No filler phrases: no 'In today's rapidly evolving', no 'Let's dive in', no 'It's worth noting', no 'In conclusion', no 'I hope this was helpful'. No banned words: incredible, amazing, leveraging, synergize, game-changing, groundbreaking, revolutionary, paradigm, cutting-edge, seamless, robust, unprecedented, delve, harness, utilize, transformative, disruptive, unlock, comprehensive, actionable, crucial, pivotal. Title must not start with I, My, or We. Open with a hook paragraph that does not announce the topic. Close with something actionable. Do not invent claims, metrics, or outcomes not present in the source material."
+    }]
+  },
+  "contents": [{
+    "parts": [{
+      "text": "RAW_CONTENT_AND_INSTRUCTIONS_HERE"
+    }]
+  }],
+  "generationConfig": {
+    "temperature": 0.7,
+    "maxOutputTokens": 4096
+  }
+}
+ENDJSON
+```
+
+Replace `RAW_CONTENT_AND_INSTRUCTIONS_HERE` with:
+- The raw input content
+- The blog post style and structure instructions (from the selected template)
+- Any Tavily research results gathered in Step 4
+- Word target: 800-1,800 words
+
+Post the request:
+
+```bash
+curl -s -X POST \
+  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/noise2blog-request.json \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
+```
+
+Also produce:
+- (B) A 1-2 sentence meta description for SEO preview text
+- (C) One alternative title using a different hook angle
+
+---
+
+## Step 6: Self-QA
+
+Run every check and fix violations before presenting:
+
+- [ ] Title does not start with "I", "My", or "We"
+- [ ] Title is specific and conversational (not "A Comprehensive Guide to X" or "The Ultimate Guide to Y")
+- [ ] Opening paragraph hooks without announcing the topic ("In this post I will...")
+- [ ] No em dashes in any line
+- [ ] No semicolons
+- [ ] No paragraph longer than 3 lines before a blank line
+- [ ] No banned words: incredible, amazing, leveraging, game-changing, delve, harness, unlock, groundbreaking, cutting-edge, remarkable, paradigm, revolutionize, seamless, robust, utilize, unprecedented, comprehensive, actionable, crucial, pivotal
+- [ ] No invented data: every claim traces to the raw input or a Tavily result
+- [ ] Post does not end with "In conclusion", "To summarize", or "I hope this helped"
+- [ ] 800-1,800 words (state the word count)
+- [ ] Logical flow: opening → problem/context → body sections → actionable close
+
+Fix any violation before presenting. State the final word count.
+
+---
+
+## Step 7: Output
+
+Present the full blog post in a code block.
+
+Present the meta description and alternative title below the main post.
+
+Ask: "Ready to copy this to your editor? If you're publishing to a specific platform, let me know and I can format the frontmatter."
+
+**On platform-specific request:**
+
+Ghost:
+```yaml
+---
+title: "POST_TITLE"
+date: YYYY-MM-DD
+tags: [tag1, tag2]
+status: draft
+---
+```
+
+dev.to:
+```yaml
+---
+title: POST_TITLE
+description: META_DESCRIPTION
+tags: [tag1, tag2, tag3]
+published: false
+---
+```
+
+Substack: Present as plain Markdown. Substack's editor imports markdown directly.
+
+Hashnode:
+```yaml
+---
+title: POST_TITLE
+subtitle: META_DESCRIPTION
+tags: [tag1, tag2]
+---
+```
+
+

package/skills/noise2blog/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "noise2blog",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write a blog post from these notes: [pasted bullet points about a debugging session — found a race condition in a queue worker, fixed it by adding a mutex, 3 days of debugging, specific error messages mentioned]",
+      "expected_output": "Agent detects bullet points / rough notes as input type. Identifies core thesis (debugging race condition in queue worker). Chooses Case Study style based on narrative signals. Reads blog-format.md and output-template.md. Calls Gemini with anti-slop system prompt. Produces 800-1,400 word blog post: title does not start with I/My/We, opening paragraph hooks without announcing topic, no em dashes, no banned words, 1-3 line paragraphs with blank lines. States word count. Presents meta description and alternative title. Post ends with actionable close, not summary statement.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Turn this voice transcript into a blog post: [rambling transcript with filler words, repeated ideas, conversational tone — about switching from REST to GraphQL, mentions 40% reduction in overfetching, team pushback initially]",
+      "expected_output": "Agent detects voice transcript input type. Strips filler language during analysis. Identifies core thesis (REST to GraphQL migration, measurable outcome). Detects Case Study or Thought Leadership style. If TAVILY_API_KEY is set, searches for supporting data on GraphQL adoption or overfetching benchmarks. Produces clean blog post that sounds like a real person — contractions present, no banned words. The specific 40% reduction number appears in the post since it came from the source material. Does not invent additional metrics. States word count.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Turn this tweet thread into a blog post: [10 tweets arguing that most devs optimize the wrong database queries, mentions a specific production incident, no stats cited]",
+      "expected_output": "Agent detects tweet thread dump input type. Identifies Thought Leadership style from the contrarian argument signals. Notes that no statistics are cited in the raw input. If TAVILY_API_KEY is set, optionally searches for database query optimization data to support claims — but only uses results that confirm claims already in the tweets, does not introduce new arguments. Produces blog post using Thought Leadership template: claim stated in opening, common assumption section, evidence section, counterargument, nuance, actionable close. No invented metrics. Word count stated.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Write a blog post from this URL: https://example-engineering-blog.com/article",
+      "expected_output": "Agent fetches URL content using WebFetch. Extracts title, body text, statistics, and structure. Identifies input type as article/URL. Detects blog style from content signals. Reads format rules and selects appropriate template. Generates blog post — does not plagiarize source, synthesizes the content into a new post in the author's voice. Every claim traces to content extracted from the URL. Presents word count, meta description, and alternative title. If the fetched URL returns an error, agent tells the user and asks them to paste the content directly.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Write a blog post from my notes about deploying a Node.js app",
+      "expected_output": "Agent checks for GEMINI_API_KEY — it is missing. Agent stops immediately at Step 1. Tells the user: 'GEMINI_API_KEY is required. Get it at aistudio.google.com → Get API key. Add it to your .env file.' Does not attempt to fetch content or generate anything without the API key.",
+      "files": []
+    }
+  ]
+}

package/skills/noise2blog/references/blog-format.md

@@ -0,0 +1,188 @@
+# Blog Format Guide
+
+## Section 1: Why Format Matters
+
+Most blog posts fail at the first paragraph. Readers scan — they read the title, the first sentence, and maybe one or two more. If nothing grabs them, they're gone. Format is not about aesthetics: it is about keeping someone reading past the first scroll.
+
+Short paragraphs signal that reading this will not be painful. Concrete details signal that the author has done real work. A specific title signals that the post is about one thing, not a vague survey of a topic.
+
+---
+
+## Section 2: Title Rules
+
+The title is the single highest-leverage element. A bad title kills a good post.
+
+Must:
+- Name the specific thing the post is about
+- Create a reason to click (curiosity gap, specific benefit, or counterintuitive claim)
+- Be under 70 characters
+- Use conversational English
+
+Must not:
+- Start with "I", "My", or "We"
+- Use: "A Comprehensive Guide to", "The Ultimate Guide to", "Everything You Need to Know About"
+- Use clickbait that the post does not deliver on
+
+Formats that work:
+- Specific result: "How we cut deploy time from 47 minutes to 4"
+- Counterintuitive claim: "The feature our users love most took 2 hours to build"
+- How-to with specifics: "How to set up agent memory that actually persists"
+- Problem statement: "Why your RAG pipeline is slower than it needs to be"
+- Tool comparison with a point: "Playwright vs Puppeteer: what actually matters for E2E tests"
+
+---
+
+## Section 3: Opening Paragraph Rules
+
+The opening paragraph must hook without announcing what you are about to do.
+
+Must not:
+- "In this post, I will..."
+- "Today we're going to explore..."
+- "This article covers..."
+- "Welcome to this guide on..."
+- Any variation of "let's dive in"
+
+Do:
+- Open with the most surprising or concrete thing from the post
+- State a problem the reader recognizes
+- Make a bold claim you will back up
+- Drop into a specific moment or situation
+
+Examples that work:
+- "We spent three weeks debugging a race condition that turned out to be a single missing await."
+- "Most developers add caching too late. By the time you notice the N+1 query, your database is already the bottleneck."
+- "The CSV export feature took two hours. Users mentioned it in 40% of support tickets."
+
+---
+
+## Section 4: Body Rules
+
+**Paragraph length:** 1-3 lines max, then a blank line. Never 4 consecutive lines without a break.
+
+**Sentence length:** Mix short and long. Short sentences hit hard. Then follow up with a sentence that gives context, adds nuance, or shows the reader why it matters.
+
+**Specificity:** Every section needs at least one concrete detail — a number, a file name, a command, a tool name, a before/after comparison. Remove any sentence that could apply to any post on the topic.
+
+**Headers (H2):** 3-5 major sections. Each section covers one idea. Use headers to break the scan path for readers who skip ahead.
+
+**Code blocks:** Use triple-backtick fenced blocks. Never inline code in a paragraph when a block would be clearer.
+
+**Lists:** Use for steps, options, or comparisons. Do not force a list when prose would flow better.
+
+---
+
+## Section 5: Story Arcs by Style
+
+### Technical Tutorial
+```
+[Hook — the end result, or what most people get wrong about this]
+[Why this matters — who this is for, what problem it solves]
+[Prerequisites — only what is actually needed]
+[Step 1 — one action]
+[Step 2 — one action]
+[Step 3 — one action]
+[Common mistake — what breaks here and why]
+[Result — what working looks like]
+[Actionable close — next step or variation]
+```
+
+### Case Study
+```
+[Hook — the end result or the key moment that changed things]
+[Setup — where things started, what the problem was]
+[Decision — what was tried or changed]
+[What happened — the outcome, including surprises]
+[What we learned — the lesson extracted]
+[What to take from this — for the reader, not just the author]
+[Actionable close]
+```
+
+### Thought Leadership
+```
+[Hook — the contrarian claim stated directly]
+[The assumption — what most people believe and why]
+[The evidence — what you actually observed]
+[The implication — what changes if the claim is true]
+[The counterargument — steelman the other side]
+[The rebuttal — why the position holds]
+[The nuance — edge cases and when this does not apply]
+[Actionable close — what should change as a result]
+```
+
+### Explainer
+```
+[Hook — what knowing this enables, or the common misconception]
+[The problem with the standard explanation]
+[What X actually is — plain English, one paragraph]
+[How it works — mechanism, not just definition]
+[Real example — concrete, not hypothetical]
+[When to use it vs alternatives]
+[Actionable close — try this or read this next]
+```
+
+---
+
+## Section 6: Closing Rules
+
+End with exactly one of:
+- An actionable next step: "Try this on your next feature branch and check if the diff size changes."
+- A direct question that invites real responses: "What's the bottleneck in your current setup?"
+- A pointer to the next logical resource: "If this applies to your stack, the GitHub repo is in the description."
+
+Do not use:
+- "In conclusion..."
+- "To summarize..."
+- "I hope this was helpful."
+- "Thanks for reading."
+- Two CTAs at once
+
+---
+
+## Section 7: Length Guide
+
+| Post type | Target word count |
+|-----------|------------------|
+| Tutorial (focused, one task) | 800-1,200 words |
+| Case study (a real story) | 1,000-1,600 words |
+| Thought leadership (one argument) | 800-1,400 words |
+| Explainer (one concept) | 900-1,500 words |
+
+Under 600 words feels shallow unless it is a quick tip. Over 2,000 words requires a very strong argument for staying that long.
+
+---
+
+## Section 8: Banned Words
+
+Do not use any of these in any paragraph or heading:
+
+incredible, amazing, leveraging, synergize, game-changing, game changer, let's dive in, buckle up, it's worth noting, delve, harness, unlock, groundbreaking, cutting-edge, remarkable, paradigm, revolutionize, disruptive, transformative, thrilled, excited to share, powerful, innovative, comprehensive, actionable, crucial, vital, pivotal, elucidate, utilize, robust, seamless, unprecedented, state-of-the-art, at its core, the landscape of, in the world of, whether you're a beginner or an expert, from X to Y this covers everything, look no further, in today's rapidly evolving
+
+If you see one of these in a draft section, rewrite that sentence before presenting.
+
+---
+
+## Section 9: No Em Dashes
+
+Do not use em dashes (—) anywhere in the post. Replace with:
+- A comma where a pause belongs
+- A period to break a long sentence into two
+- A colon before an explanation
+
+---
+
+## Section 10: Validation Checklist
+
+Before presenting the draft, verify:
+
+- [ ] Title does not start with "I", "My", or "We"
+- [ ] Title is specific (not "a guide", not "the ultimate", not "everything about")
+- [ ] Opening paragraph hooks without announcing the topic
+- [ ] No em dashes in any line
+- [ ] No semicolons
+- [ ] No paragraph longer than 3 lines without a blank line
+- [ ] No banned words
+- [ ] Every claim traces to the raw input or a Tavily result
+- [ ] Post ends with an action, a question, or a pointer — not a summary statement
+- [ ] Word count is in target range (state the count)
+- [ ] Logical flow throughout (each section leads to the next)

package/skills/noise2blog/references/output-template.md

@@ -0,0 +1,184 @@
+# Output Templates
+
+Four templates: Technical Tutorial, Case Study, Thought Leadership, Explainer.
+
+Select the template that matches the detected or user-specified style. Replace every [BRACKETED SLOT] with content from the raw input. Never leave bracket text in the output. Skip a slot entirely if there is no source material for it — do not invent content to fill it.
+
+---
+
+## Template 1: Technical Tutorial
+
+Use when the raw content is a step-by-step guide, how-to, or code walkthrough.
+
+```markdown
+[TITLE — specific result or what most people get wrong. Under 70 chars. Does not start with I/My/We.]
+
+[HOOK — 2-3 sentences. The end result a reader achieves, or the mistake most people make. No "In this post". No "Let's dive in".]
+
+[CONTEXT — 1-2 sentences. Who this is for and what problem it solves. Be specific about the situation.]
+
+## [PREREQUISITE SECTION TITLE — e.g. "What you need"]
+
+[List only prerequisites that are genuinely required. Skip this section if there are none.]
+
+## [STEP 1 TITLE — one action, named concretely]
+
+[Step 1 content. One task. Include the command, code, or UI action. 1-3 paragraphs max.]
+
+## [STEP 2 TITLE]
+
+[Step 2 content.]
+
+## [STEP 3 TITLE]
+
+[Step 3 content.]
+
+## [OPTIONAL: STEP 4 TITLE — common mistake or edge case at this stage]
+
+[What breaks here and why. Only include if the raw input mentions it.]
+
+## [RESULT TITLE — e.g. "What it looks like when it works"]
+
+[2-3 sentences describing the working end state. Include a concrete output — a log line, a screenshot description, a returned value.]
+
+[ACTIONABLE CLOSE — one specific next step or variation the reader can try. Not "I hope this was helpful".]
+```
+
+**Worked example:**
+
+Raw input: Rough notes on setting up Playwright for E2E tests in a Next.js app — mentions `npx playwright install`, a config file location, the `page.goto()` pattern, and a note that webkit tests fail without a specific environment variable.
+
+Generated title: "Setting up Playwright in a Next.js app without breaking webkit tests"
+
+Generated opening: "Playwright installs in one command. Getting webkit tests to actually run in CI takes a bit more. Here's the setup that works without the two-hour debugging session."
+
+---
+
+## Template 2: Case Study
+
+Use when the raw content is a build log, before/after story, lessons-learned post, or first-person journey.
+
+```markdown
+[TITLE — the end result or the key moment. Under 70 chars. Does not start with I/My/We.]
+
+[HOOK — 2-3 sentences. The end state or the most surprising outcome from the story. Drops the reader into the situation.]
+
+## [CONTEXT TITLE — e.g. "Where things started" or the specific problem]
+
+[Setup: what the situation was before. Be specific about the pain or the constraint. 1-2 paragraphs.]
+
+## [DECISION TITLE — e.g. "What we tried" or "The change we made"]
+
+[The specific action taken. What was built, changed, or dropped. Include concrete details: what was replaced with what, how long it took, who was involved.]
+
+## [OUTCOME TITLE — e.g. "What happened" or "The result"]
+
+[The outcome, including anything unexpected. Specific numbers if available. Do not invent metrics not in the source.]
+
+## [LESSON TITLE — e.g. "What we learned" or "The thing nobody warned us about"]
+
+[The extracted insight. Should be transferable to someone not in the exact same situation. 1-2 paragraphs.]
+
+[ACTIONABLE CLOSE — what the reader should try, check, or think about based on this story.]
+```
+
+**Worked example:**
+
+Raw input: Voice transcript about rebuilding a feature that served 10k users — mentions moving from a cron job to an event-driven queue, reducing latency from 8 seconds to 400ms, and the unexpected issue with message ordering after the switch.
+
+Generated title: "Moving 10,000 users from a cron job to a queue: what nobody tells you about message ordering"
+
+---
+
+## Template 3: Thought Leadership
+
+Use when the raw content makes a strong opinion claim, argues against common advice, or takes a counterintuitive position.
+
+```markdown
+[TITLE — the contrarian claim stated directly. Under 70 chars. Does not start with I/My/We.]
+
+[HOOK — 2-3 sentences. The claim, stated plainly. Do not hedge. The reader should immediately know what you're arguing.]
+
+## [THE ASSUMPTION — e.g. "What most teams believe"]
+
+[1-2 sentences stating the common belief. Be fair to the other side.]
+
+[1-2 sentences explaining why people hold this belief. What evidence supports it?]
+
+## [THE EVIDENCE — e.g. "What actually happens" or "What the data shows"]
+
+[Specific observations, results, or data points from the raw input. This is the core of the argument. 2-3 paragraphs.]
+
+## [THE IMPLICATION — e.g. "What changes if this is true"]
+
+[Concrete consequences of accepting the claim. What should readers do differently? 1-2 paragraphs.]
+
+## [THE COUNTERARGUMENT — e.g. "The case against this"]
+
+[Steelman the other side. The strongest objection to the claim. 1 paragraph.]
+
+## [THE NUANCE — e.g. "When I'm wrong"]
+
+[Edge cases. When does the claim not hold? Being honest here makes the argument stronger. 1 paragraph.]
+
+[ACTIONABLE CLOSE — what the reader should try or reconsider based on the argument. Ask for pushback specifically if the post invites debate.]
+```
+
+**Worked example:**
+
+Raw input: Tweet dump arguing that code reviews slow down small teams more than they help — mentions two data points about merge time, a quote from a teammate, and a suggestion to use async video reviews instead.
+
+Generated title: "Code reviews are slowing your small team down"
+
+---
+
+## Template 4: Explainer
+
+Use when the raw content explains a concept, tool, or trend for readers who are not already familiar with it.
+
+```markdown
+[TITLE — what knowing this enables, or the common misconception. Under 70 chars. Does not start with I/My/We.]
+
+[HOOK — 2-3 sentences. The most surprising or counterintuitive thing about this topic. Or the misconception most people have. No "In this post I'll explain".]
+
+## [PROBLEM WITH STANDARD EXPLANATION — e.g. "Why the usual explanation misses something"]
+
+[1-2 paragraphs. What's wrong or incomplete about how most sources explain this.]
+
+## [WHAT IT ACTUALLY IS — e.g. one clear, plain English section title]
+
+[Plain English definition. One paragraph. No jargon unless immediately explained.]
+
+## [HOW IT WORKS — the mechanism]
+
+[The underlying mechanism, not just the interface. 2-3 paragraphs. Use an analogy if it helps. Include a concrete example — a specific tool, command, or situation.]
+
+## [REAL EXAMPLE — specific, not hypothetical]
+
+[Walk through one real use case. Name specific files, tools, or scenarios from the raw input. Do not use generic placeholder examples like "imagine you have an app".]
+
+## [WHEN TO USE IT — and when not to]
+
+[1-2 concrete situations where this is the right choice. 1-2 where it is the wrong choice. Be specific.]
+
+[ACTIONABLE CLOSE — what to try next. A command to run, a resource to read, or a question to ask yourself.]
+```
+
+**Worked example:**
+
+Raw input: Notes explaining RAG (retrieval-augmented generation) to developers who've heard the term but don't understand why it's better than fine-tuning — includes an analogy to open-book exams vs memorizing, mentions specific latency tradeoffs.
+
+Generated title: "RAG is not just a smarter search: what the open-book analogy gets wrong"
+
+---
+
+## Fill-In Rules
+
+1. Replace every [BRACKETED SLOT] with content from the raw input or Tavily results
+2. Never leave bracket text in the output
+3. Skip any slot that has no source material — do not invent content to fill it
+4. If a section has no relevant source content, remove the section header too
+5. Adjust sections to match the actual content (add or remove H2 sections as needed)
+6. Apply all rules from blog-format.md to every paragraph and sentence
+7. Count words before presenting; state the count
+8. Every claim in the output must trace to the source input or a named Tavily result

package/skills/outreach-sequence-builder/.env.example

@@ -0,0 +1,12 @@
+# outreach-sequence-builder — Environment Variables
+# ===================================================
+# Gemini is required. Composio is optional (enables Gmail draft creation).
+
+# Required: Google Gemini API key for sequence generation
+# Get it: aistudio.google.com, Get API key
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Optional: Composio API key for Gmail draft creation
+# Get it: app.composio.dev, API Keys section
+# Without this key, sequences are output as formatted text for copy-paste only
+COMPOSIO_API_KEY=your_composio_api_key_here