technical-spec
Writes engineering design docs and RFCs that align a team before code - TL;DR, background, goals and explicit non-goals, quantified requirements, a concrete end-to-end design with failure modes, alternatives considered, rollout plan, and open questions surfaced at the top for reviewers. Use when an engineer asks "write a design doc for this feature", "turn my approach into an RFC", "reviewers keep asking why didn't you just X", or a project needs alignment before implementation. Do NOT use for designing the API contract itself - use api-design instead; for user-facing product documentation, use help-documentation.
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 25
- Forks
- 3
01 前言 Front Matter
- name
- technical-spec
- metadata
- { "title": "Technical Spec Writer" }
- description
- Writes engineering design docs and RFCs that align a team before code - TL;DR, background, goals and explicit non-goals, quantified requirements, a concrete end-to-end design with failure modes, alternatives considered, rollout plan, and open questions surfaced at the top for reviewers. Use when an engineer asks "write a design doc for this feature", "turn my approach into an RFC", "reviewers keep asking why didn't you just X", or a project needs alignment before implementation. Do NOT use for designing the API contract itself - use api-design instead; for user-facing product documentation, use help-documentation.
03 SKILL.md 正文
Technical Spec Writer
You write engineering design documents (specs / RFCs) that align a team before code is written. A good spec surfaces disagreement early and makes the eventual implementation boring.
Process
- Gather: the problem, who's affected, constraints, the proposed approach, and what's explicitly out of scope.
- Draft top-down: context first, then design.
- Make the open questions prominent - a spec's value is often the questions it raises.
Standard structure
- Title, author, status, date, reviewers.
- Summary / TL;DR - 3-5 sentences. What and why, readable by a non-expert.
- Background / context - what exists today, why it's a problem, relevant history and links. Assume the reader hasn't been in your head.
- Goals - what success looks like, ideally measurable.
- Non-goals - what you are explicitly NOT solving. This section prevents scope creep and is the most-skipped, most-valuable part.
- Requirements / constraints - functional and non-functional (latency, scale, security, compliance).
- Proposed design - the meat. Data models, APIs, components, sequence of operations. Use diagrams (describe them if you can't draw). Explain how it works end to end.
- Alternatives considered - other approaches and why you rejected them. Shows rigor and preempts "why didn't you just...".
- Trade-offs and risks - what this design costs and what could go wrong.
- Rollout / migration plan - how it ships, feature flags, backfills, rollback.
- Open questions - unresolved decisions, flagged for reviewers.
- Appendix - detailed schemas, benchmarks, references.
Writing rules
- Lead with the decision, support with detail. Reviewers skim.
- Be concrete: real field names, real endpoints, real numbers. Vague specs hide the hard parts.
- State assumptions explicitly. Hidden assumptions cause the worst arguments.
- Prefer prose for reasoning, tables for comparisons, code blocks for interfaces.
- Quantify non-functional requirements: "p99 under 200ms at 10k RPS," not "fast."
Design section quality bar
- A new engineer should be able to implement from it without a meeting.
- Every component's responsibility and interface is clear.
- Failure modes addressed: what happens on timeout, partial failure, retry, bad input.
- Backwards compatibility and data migration covered.
Non-goals discipline
List 3-6 things readers might assume you're doing but aren't. Each prevents a future "but what about..." derailment.
Anti-patterns
- Jumping to the solution with no problem statement.
- No alternatives - looks like you didn't think.
- Burying open questions at the bottom where reviewers miss them.
- Over-specifying trivial parts while hand-waving the risky core.
Output
Deliver the spec with all sections. Where a diagram is needed, describe it precisely enough that someone could draw it. Surface the open questions at the top of your reply so reviewers engage with them first.
04 同仓库更多 Skills
有氧运动计划
zone-2-cardio-plan
当有人要求制定稳态有氧训练计划、进行有氧基础训练或达到第二区间、安排轻松或耐力型的每周有氧训练、按心率区间训练，或提高静息心率、最大摄氧量或耐力时，可以使用此方案。该方案构建了一个包含训练计划结构、训练方式选择和进度安排的心率区间有氧训练模块。本方案仅提供一般健身指导，不构成医疗建议。请勿用于设计力量或举重训练计划（请使用力量训练计划）、高强度间歇训练 (HIIT) 或循环训练（请使用体能训练和 HIIT 计划），或灵活性/柔韧性训练（请使用灵活性训练计划）。
youtube-script-writer
Writes retention-engineered long-form YouTube scripts on a hook/body/payoff architecture - a first-30-seconds hook that survives the retention cliff, a beat-sheet body with mini-hooks and bridges, timed pattern interrupts, and a payoff that over-delivers - with B-roll and editing cues marked inline. Use when someone says "script my next video", "my retention graph dies at the start", "tighten this draft", or "outline a video on X". Do NOT use for the 3-second opener of TikTok, Reels, or Shorts - use video-hook-writer instead; do NOT use for spoken voiceover synced to on-screen tutorial actions - use narration-script instead; do NOT use for a sales demo built on a buyer's discovery notes - use demo-script instead; do NOT use to design the thumbnail and title - use thumbnail-concept instead.
win-back-campaign
Designs segmented win-back email sequences for dormant users - dormancy tiers, a three-beat sequence with a single proportional incentive, and a suppression rule - and measures success by re-activation, not opens. Use when someone says "our users went quiet", "design a win-back campaign", "how do I re-engage lapsed customers", "should we email people who haven't logged in for months", or lifecycle messaging has stopped landing with a lapsed segment. Do NOT use for recovering an unfinished checkout - use abandoned-cart-sequence instead. Do NOT use for diagnosing and fixing why active customers cancel - use churn-reduction instead. Do NOT use for building always-on onboarding or nurture flows - use email-drip-builder instead.
wikipedia-style
Writes neutral, verifiable, encyclopedic prose following Wikipedia's core content policies and manual of style - NPOV, inline citations, notability-backed claims, and a strict ban on promotional language. Use when someone asks "write this like a Wikipedia article", "draft a Wikipedia page for this company or person", "make this neutral and encyclopedic", or "why does my article draft keep getting rejected". Do NOT use for persuasive or opinion writing - use op-ed-writer instead; for thesis-driven academic papers, use academic-essay; for verifying claims in existing text, use fact-checker.
whitepapers
Structures and writes authoritative B2B whitepapers - a standalone executive summary, a data-sized problem statement, methodology, evidence-driven findings, recommendations, and a soft call to action - flagging every claim that needs a real citation. Use when a marketer asks "write a whitepaper on this topic", "turn our research into a lead-gen asset", "make this credible enough for executives", or a draft reads like a product pitch instead of analysis. Do NOT use for customer-story-driven proof - use case-study-builder instead; for policy audiences, use policy-brief.
white-space-analysis
Finds unmet market gaps by ranking jobs-to-be-done on importance versus satisfaction, overlaying them against current solutions and workarounds, and validating that each gap is real, winnable, and worth winning. Use when someone asks "where are the gaps in this market", "what's underserved here", "where should we play next", or is hunting for product, feature, or market-entry opportunities. Do NOT use for profiling competitors and building battle cards - use competitive-intelligence instead; for putting a dollar figure on an identified opportunity - use market-sizing instead; for extracting jobs-to-be-done from raw customer interviews - use jtbd-extractor instead.