0xF4ng/aether-growth-fieldwork / foundations/shared-skills/content-craft
content-craft
VerifiedWriting production workflow for technical B2B and developer-community content pieces. Invoke when an author needs to produce a migration story, technical deep dive, architectural decision piece, how-to guide, or thought-leadership article from scratch. This skill selects the right story framework, produces the draft structure, and runs a pre-publish editorial checklist. It does not review completed content — use `pmm/content-review/SKILL.md` for that gate. Appropriate for any technical B2B product; no brand-specific knowledge required.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.5 KB |
SKILL.md
View on GitHub---
name: content-craft
description: >-
Writing production workflow for technical B2B and developer-community content
pieces. Invoke when an author needs to produce a migration story, technical
deep dive, architectural decision piece, how-to guide, or thought-leadership
article from scratch. This skill selects the right story framework, produces
the draft structure, and runs a pre-publish editorial checklist. It does not
review completed content — use `pmm/content-review/SKILL.md` for that gate.
Appropriate for any technical B2B product; no brand-specific knowledge required.
triggers:
- /content-craft
- /write-article
- user wants to draft a technical article or blog post
- user says "help me write a story about"
- user says "I built X, help me write it up"
- user says "we migrated from X, help me tell that story"
role: workflow
version: 1.0.0
sources:
- "b2b-practitioner-voice (growth-skills v1.0, score 9/10)"
- "dev-infra-community-story (growth-skills v1.0, score 9/10)"
feeds:
- pmm/content-review/SKILL.md
related:
- pmm/DOMAIN.md
- pmm/brand-calibration/SKILL.md
- growth/DOMAIN.md
---
# Content Craft — Writing Production Workflow
## Contract
This skill guarantees:
- Framework selection is driven by the author's story type, not forced on an ill-fitting piece
- Every draft produced follows the practitioner voice standard in `pmm/DOMAIN.md`
- Editorial checklist runs before the draft is handed to content-review
- Anti-patterns are flagged before the draft leaves this workflow
- Output is a structurally complete draft with all required sections populated, not a bullet outline
---
## Brain reads / writes
**Before starting**, if a companion `aether-growth-brain` repo is connected:
- Read `knowledge/icp-map.md` — confirm the intended audience aligns with a validated ICP card; flag if the intended audience does not match any ICP in the map
- Read `playbooks/messaging.md` — if approved positioning exists, the article's framing must not contradict it; bring any approved category terms into the draft deliberately
**On completion**, write a one-line log entry to `decisions/content-craft-log.md`:
```
[date] [article-title] | framework: [A/B/C/D/E] | ICP: [role] | verdict: DRAFT_COMPLETE
```
---
## Inputs
### Required before proceeding
| Input | Notes |
|---|---|
| **Author's raw material** | Notes, bullet points, or a rough draft. This skill does not invent engineering facts. If raw material is missing, return `NEEDS_CONTEXT`. |
| **ICP definition** | Role, seniority, primary pain category. "Technical audience" is not enough — specify (e.g. "backend engineers at mid-market SaaS, migration pain"). |
| **At least one real constraint** | A specific bottleneck, error message, metric, or decision that drove the story. Vague setups produce vague stories. |
| **Product truth doc or approved terminology** | Official names, banned aliases, component names. This skill does not invent naming. |
### Optional but improves output
| Input | Effect |
|---|---|
| Destination platform | Adjusts length target and CTA approach (blog, HN, LinkedIn, community forum) |
| Competitor context | Enables a fair comparison arc in Framework A or C |
| Published examples from the same program | Calibrates terminology precision and voice |
### BLOCK rule
```
If raw material (author's actual engineering experience) is missing:
BLOCK. Return:
"This skill does not invent engineering facts. Please provide:
- What you built, migrated, or decided (and why)
- At least one real constraint, error, or metric from your experience
- What you tried that didn't work
I can then help shape and write."
```
---
## Decision logic — framework selection
Do not blend two frameworks in one piece. Select the dominant framework based on the author's story.
### Framework selection criteria
| If the author says… | Select |
|---|---|
| "We moved from X to Y" / "We migrated from…" | **Framework A — Migration story** |
| "I built X using [product/technology]" / "Here's how we implemented…" | **Framework B — Technical deep dive** |
| "We chose X over Y and Z" / "Here's why we picked…" | **Framework C — Architectural decision** |
| "Here's how to do X" / "Step-by-step guide for…" | **Framework D — How-to guide** |
| "The industry is wrong about X" / "Here's a new way to think about…" | **Framework E — Category narrative** |
**When the story could fit multiple frameworks:** ask the author which element they most want readers to remember. The memorable takeaway determines the framework.
**Do not force a framework on a short piece.** Under 600 words: use practitioner voice mechanics only (no framework structure required). Respect the surface.
---
## Framework structures
### Framework A — Migration story
Target: 1,800–2,500 words
| Section | Focus | Target words |
|---|---|---|
| **The Pain** | Name the problem with a specific term the reader recognizes instantly as their own. Structure pain across at least 2 of 3 dimensions: operational inconvenience + engineering/performance risk + compliance/cost risk. Anchor with exact errors, failure times, SLA misses. | 300–400 |
| **The Dead Ends** | Fair comparison arc: 2–3 alternatives, each given their strongest case first. Format per alternative: what it does well → where it specifically failed for your workload → why that was disqualifying. Never strawman. Engineers who evaluated the same options will catch it. | 200–300 |
| **Why This Solution** | The reframing move: "Instead of [old mental model], we started thinking of [new frame]." Then map specific capabilities to the named constraints from The Pain — feature → mechanism → specific workflow → outcome. Not a feature list. | 300–400 |
| **The Work** | Migration strategy, code, config, unexpected challenges. Show the struggle: what you tried first and why it failed, what you learned, how that led forward. | 600–900 |
| **The Outcome** | Measured results with full methodology context. What you gave up. What you would do differently. Close with one specific, understated production metric delivered matter-of-factly. | 300–400 |
### Framework B — Technical deep dive
Target: 1,500–2,200 words
| Section | Focus | Target words |
|---|---|---|
| **The Goal** | What is being built and why it is technically interesting. Name the constraint or capability gap that made this worth building. | 200–300 |
| **The Stack** | Technology choices and the reasoning behind them. Constraints drove these choices — name them. | 150–200 |
| **The Architecture** | System design with the key decision points. For complex systems, include a diagram placeholder. | 300–400 |
| **The Implementation** | Step-by-step code walkthrough. Every code block wrapped with context-before-code rule (see `pmm/DOMAIN.md`). Show at least one wrong turn or unexpected challenge. | 700–1,000 |
| **The Result** | Demo link, repo, benchmark, lessons, next steps. Close with one specific production or scale signal. | 200–300 |
### Framework C — Architectural decision
Target: 1,200–1,800 words
| Section | Focus | Target words |
|---|---|---|
| **The Scenario** | Requirements with specific numbers: throughput, dataset size, latency target, consistency model. Name the constraint that made "keep the current setup" no longer viable. | 250–350 |
| **The Options** | Fair comparison arc: 2–3 alternatives. Per option: what it does well → specific limitation for this workload → disqualifier. Give each alternative its strongest case before naming why it didn't fit. | 500–700 |
| **The Evaluation** | How you tested (tools, methodology, dataset). Specific metrics from the POC. Include at least one structural contrast if relevant: "X was designed for [old assumption] — our workload no longer fits that assumption because [why]." | 300–400 |
| **The Verdict** | Technical justification. Explicitly name what you are giving up. | 200–300 |
### Framework D — How-to guide
Target: 800–1,500 words
| Section | Focus | Target words |
|---|---|---|
| **The Goal** | What the reader will be able to do after following this guide. Name the specific outcome. | 100–150 |
| **Prerequisites** | Exact requirements (versions, access, prior steps). Do not skip these — missing prerequisites are the primary cause of tutorial failure. | 100–150 |
| **Steps** | Numbered steps. Every step has a clear action verb. Every code block wrapped with context-before-code rule. Include at least one "gotcha" or common failure point per major step. | 500–900 |
| **Validation** | How to confirm it worked. Specific output or state to verify. | 100–150 |
| **Next step** | One concrete next action or resource — not a list of five things. | 50–100 |
### Framework E — Category narrative (thought leadership)
Target: 1,000–1,800 words
| Section | Focus | Target words |
|---|---|---|
| **The Market Shift** | Name the structural change making the old approach inadequate. One specific, observable signal — not generic "the world is changing." | 200–300 |
| **The Broken Assumption** | The assumption the old approach was built on — now violated. State it precisely. | 200–300 |
| **The New Model** | "Instead of X, think of Y." The reframing move. One memorable frame — not a list of five improvements. | 300–400 |
| **The Structural Implication** | What changes in how people work, build, or buy as a result of the new model. Product appears here as evidence, not feature list. | 200–300 |
| **The Hard Question** | End on a question or sharpened worldview — not a CTA. The question should be one the reader cannot dismiss. | 100–150 |
---
## Editorial mechanics (apply to all frameworks)
These mechanics are defined in full in `pmm/DOMAIN.md`. Summary for reference during drafting:
| Mechanic | Rule |
|---|---|
| **Context-before-code** | 2–3 sentences before every code block (what/why/how). 1–2 sentences after (what to notice/result). Never place a code block immediately after a section header. |
| **Show the struggle** | At least one wrong turn per major decision: what you tried, why it failed, what you learned. A piece with no wrong turns reads as marketing. |
| **Metrics-with-methodology** | Never bare numbers. Always state: what was tested, how it was tested, why the number matters. |
| **Problem naming** | Coin a specific term the reader recognizes as their own pain. Not generic framing — a name they would use in a 2 AM Slack message. |
| **Reframing move** | At the turn from problem to solution: "Instead of X, think of Y." One sentence. Acknowledges the reader's current model; makes the solution feel inevitable. |
| **Feature-to-use-case translation** | Never introduce a capability without immediately translating it: capability → one-sentence mechanism → specific workflow → measurable outcome. |
| **Scale proof as closer** | Close technical stories with one specific, understated production metric. Specific beats approximate. Understated beats promoted. |
| **Trusted-source proof chain** | All proof attributed to named company + named role + specific metric. "A large enterprise customer" = noise. |
---
## Output format
Produce in three passes:
### Pass 1 — Brief confirmation (before drafting)
```
## Content Craft — Brief Confirmation
**Framework selected:** [A / B / C / D / E] — [name]
**Reason:** [one sentence on why this fits the author's story]
**ICP:** [role, seniority, pain]
**Platform target:** [if provided]
**Target word count:** [range]
**Named problem:** [the specific term that will anchor the piece]
**Key constraint to anchor:** [the specific bottleneck, error, or metric]
**Wrong turn to include:** [what failed first]
**Closer metric:** [the production/scale signal for the ending]
Proceed to draft? [yes / no / adjustments needed]
```
### Pass 2 — Structured draft
Full draft with all framework sections populated according to the selected framework structure. All code blocks wrapped with context-before-code. All metrics with methodology. At least one wrong turn visible.
### Pass 3 — Editorial checklist
Run this checklist on the completed draft before handing to `content-review`:
**Story arc and structure**
- [ ] One framework selected; not blended with another
- [ ] Problem named with a specific term (not generic pain framing)
- [ ] Pain covers at least 2 of 3 dimensions (operational / engineering-performance / compliance-cost) — for Framework A and C
- [ ] Wrong turns visible: what was tried first and why it failed
- [ ] Reframing move present ("Instead of X, think of Y") — for Framework A, C, E
- [ ] Story closes with one specific, understated production metric or scale signal
**Voice and mechanics**
- [ ] Every code block has 2–3 sentences before it (what/why/how)
- [ ] Every code block has 1–2 sentences after it (what to notice/result)
- [ ] All metrics include: what was tested, how, why it matters
- [ ] No banned hype patterns (see `pmm/content-review/SKILL.md` banned list)
- [ ] Tone is peer-to-peer, not marketing
**Comparison content** (Frameworks A, C only)
- [ ] Each alternative receives its strongest case before limitations are stated
- [ ] Limitations are specific to the author's workload, not generic category criticisms
- [ ] No alternative described in a way the vendor would publicly dispute
**Feature translation**
- [ ] Every key capability translated: capability → mechanism → workflow → outcome
- [ ] No capability introduced naked (named without use-case translation)
**Proof chain**
- [ ] All proof attributed to named company + named role + specific metric
- [ ] No anonymous customer references ("a large enterprise")
- [ ] Product version specified where behavior is version-dependent
**Thought-leadership guardrails** (Framework E only)
- [ ] One memorable frame per piece — not a symmetrical bullet list
- [ ] Product appears as evidence of the thesis, not as a feature announcement
- [ ] Ends on a strategic question or sharpened worldview, not a CTA
---
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Inventing engineering facts | Destroys trust with the exact audience you're targeting; engineers will catch it | BLOCK and return to author for real material |
| Blending two frameworks | Reader loses the thread; the piece feels unfocused | Pick the dominant framework; relegate secondary elements to a sidebar or future piece |
| Generic pain framing | "Teams struggle with scaling" triggers nothing; reader doesn't recognize their own situation | Coin a specific term the reader would use in their own internal conversations |
| Bare metrics | "45ms latency" tells the reader nothing they can act on or compare | Always include: what was tested, how, why the number matters |
| Strawmanning alternatives | Engineers who evaluated the same options will catch it; destroys credibility for the whole piece | Give each alternative its strongest case before naming the limitation |
| Wrong turns absent | Reads as marketing, not engineering; reader cannot assess credibility | Include at least one failure, its symptom, and what it taught |
| Feature list without translation | Capability names mean nothing without the workflow they unlock | Always: capability → mechanism → specific workflow → measurable outcome |
| Forcing framework on short surface | A 300-word LinkedIn post with five H2 headings is not a framework — it's noise | Respect the surface. Under 600 words: practitioner voice only. |
| "Excited to announce" openers | Hollow enthusiasm; reader leaves immediately | Start with the news, the constraint, or the metric — not the emotion |
---
## Validation criteria
Before handing draft to `pmm/content-review`:
- [ ] All Pass 1 brief confirmation fields populated
- [ ] Draft reaches within 15% of target word count for the selected framework
- [ ] Editorial checklist completed; all items checked or explicitly noted as N/A with reason
- [ ] No banned hype patterns in author's voice (third-party quotes are exempt)
- [ ] At least one wrong turn visible in the draft
- [ ] Story closes with a specific production/scale metric or strategic question (depending on framework)
---
## References & Sources
**Tier 2 (operator templates — adapted, not authoritative):**
- b2b-practitioner-voice (growth-skills v1.0, score 9/10): practitioner voice standard, five story arcs, context-before-code rule, show-the-struggle, metrics-with-methodology, advanced storytelling patterns (problem naming, multi-layer pain architecture, reframing move, feature-to-use-case translation, scale proof as closer, trusted-source proof chain)
- dev-infra-community-story (growth-skills v1.0, score 9/10): framework A/B/C structures, word targets, pre-submit checklist, terminology precision requirements, fair comparison arc rules
**Cross-references (this repo):**
- `pmm/DOMAIN.md` — canonical practitioner voice standard, five story arcs, metrics-with-methodology; do not duplicate; defer here
- `pmm/voice-print/SKILL.md` — produces the VOICE-PRINT.md this skill should write toward (run it first when a voice profile is wanted)
- `pmm/ai-slop-audit/SKILL.md` — de-slop pass on the draft this skill produces, before content-review
- `pmm/content-review/SKILL.md` — downstream quality gate; all drafts from this skill feed content-review before publication
- `growth/newsletter-growth/SKILL.md` — owns the newsletter as a growth loop (this skill drafts the long-form; newsletter-growth decides the loop)
- `growth/short-form-social/SKILL.md` — owns LinkedIn/X short-form (this skill is long-form; don't force a framework onto a post)
- `growth/DOMAIN.md` — CLG community content types and developer story frameworks (for community-facing pieces)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |