{"id":"15a39fd0-b74f-4753-bacd-ee3beffc8fc9","shortId":"HMEvqS","kind":"skill","title":"pm-writing","tagline":"Rewrite or generate PM documents with extreme clarity. Applies principles of canonical docs, numbered lists over bullets, force-ranked priorities, BLUF structure, and visual-first communication. Transforms vague PM writing into precise, actionable docs.","description":"# PM Writing Skill\n\nTransform vague product writing into precise, actionable communication. Or generate new docs from scratch using PM writing best practices.\n\n## When to Use\n- User has a draft doc and wants it sharpened\n- User needs to write a doc from scratch with extreme clarity\n- User says `/pm-writing` followed by text to rewrite or a description\n- Any PM communication that needs to be clearer, shorter, or more actionable\n\n## Two Modes\n\n### Mode 1: Rewrite\nUser pastes existing text. Rewrite it applying all principles below. Show before/after.\n\n### Mode 2: Generate\nUser describes what they need. Generate it from scratch using the principles below.\n\n---\n\n## The 10 Principles of PM Writing\n\n### 1. Bottom Line Up Front (BLUF)\nThe first sentence of any document should answer: \"What do you need from the reader?\"\n\n**Bad:** \"Background on Q4 planning: Over the past several months, we've been evaluating various approaches to our recommendation system...\"\n**Good:** \"We need to decide by Friday whether to rebuild the recommendation engine (8 weeks) or patch the current one (2 weeks). I recommend rebuilding. Here's why.\"\n\nNever make the reader hunt for the point. Lead with the decision, ask, or conclusion.\n\n### 2. Numbered Lists Over Bullets\nUse numbered lists instead of bullet points. Numbers allow precise referencing in feedback and discussion.\n\n**Bad:**\n- Improve onboarding flow\n- Fix search latency\n- Add export feature\n\n**Good:**\n1. Improve onboarding flow (activation +15%)\n2. Fix search latency (p95 from 2s → 500ms)\n3. Add export feature (top enterprise request)\n\nNow a reviewer can say \"I disagree with #2's priority\" instead of \"the second thing you mentioned.\"\n\n### 3. One Canonical Doc Per Topic\nEvery project should have exactly one source of truth. It links to everything else but IS the definitive reference.\n\n**Structure of a canonical doc:**\n- Title, owner, last updated date\n- Status (Draft / Active / Archived)\n- The content itself (goals, decisions, open questions)\n- Links to related docs (not duplicated content)\n\nNever let the same information live in two places. When something changes, update the canonical doc.\n\n### 4. Canonical Nomenclature\nUse consistent names for things. If the feature is called \"Smart Search\" in the PRD, it's \"Smart Search\" in the design doc, the eng spec, the launch plan, and Slack.\n\n**Bad:** The doc calls it \"intelligent search,\" the ticket says \"AI search,\" and the meeting notes say \"the new search thing.\"\n**Good:** Pick one name. Use it everywhere. Put it in the canonical doc.\n\n### 5. Force-Rank, Never Group\nWhen listing priorities, never say \"these are all important.\" Stack-rank them. Ranking should feel uncomfortable — that means you're actually making choices.\n\n**Bad:** \"Our priorities this quarter are growth, quality, and platform stability.\"\n**Good:**\n1. Platform stability (P0 — nothing else matters if the system is down)\n2. Quality (P1 — retention depends on it)\n3. Growth (P2 — invest only after 1 and 2 are green)\n\n### 6. Quantify Everything\nReplace vague words with numbers. If you don't have exact numbers, estimate and flag it.\n\n**Bad:** \"This will significantly improve performance.\"\n**Good:** \"This will reduce p95 latency from 2.1s to ~500ms (estimated, need load testing to confirm).\"\n\n**Bad:** \"Many users are affected.\"\n**Good:** \"~12K MAU (18% of paid users) hit this bug weekly.\"\n\n### 7. Every Hypothesis Needs Five Parts\nNever write a vague hypothesis. Every testable claim needs:\n\n1. **Action**: What are we changing?\n2. **Metric**: What outcome are we measuring?\n3. **Magnitude**: How much change do we expect?\n4. **Segment**: For which users?\n5. **Conditions**: Under what circumstances?\n\n**Bad:** \"Adding onboarding tooltips will improve activation.\"\n**Good:** \"Adding 3-step onboarding tooltips (action) will increase D7 activation (metric) by 8-12% (magnitude) for new free-tier users (segment) who sign up via organic search (conditions).\"\n\n### 8. Make Decisions Visible\nWhen a decision is made, write it down with:\n- What was decided\n- Who decided it\n- When it was decided\n- What alternatives were considered\n- When to revisit\n\n**Format:**\n> **Decision [date]:** We will use approach B (streaming API). Decided by [owner] after evaluating batch API (too slow) and WebSocket (over-engineered). Revisit if latency requirements change.\n\n### 9. Three Options With a Recommendation\nWhen presenting a decision to stakeholders, always provide:\n- Option A (conservative)\n- Option B (moderate) — usually your recommendation\n- Option C (ambitious)\n\nFor each: one-sentence description, key trade-off, estimated effort.\n\nEnd with: \"I recommend Option B because [one sentence reason].\"\n\nNever present a problem without a recommended solution. Never present only one option (that's not a decision, it's a decree).\n\n### 10. Write for Scanners, Not Readers\nMost stakeholders will spend 30 seconds on your doc. Design for that.\n\n- **Headers** that tell the story (someone reading only headers should get the gist)\n- **Bold** the key numbers and decisions\n- **Tables** for comparisons (never compare things in paragraph form)\n- **Short paragraphs** (3 sentences max)\n- **TL;DR at the top** (always)\n\n---\n\n## Anti-Patterns to Fix\n\n| Bad Pattern | Fix |\n|---|---|\n| \"I think we should maybe consider...\" | \"We should [X]. Here's why.\" |\n| \"There are some concerns about...\" | \"Risk: [specific risk]. Mitigation: [specific action].\" |\n| \"We need to align on...\" | \"Decision needed: [specific question]. Options: [A/B/C].\" |\n| \"Going forward, we'll...\" | \"By [date], [owner] will [specific action].\" |\n| \"Various stakeholders...\" | \"[Name/team] and [name/team].\" |\n| \"Significant improvement...\" | \"[X]% improvement in [metric].\" |\n| \"ASAP\" | \"By [specific date].\" |\n| Wall of text | Numbered list with one idea per line |\n\n## Output Format\n\n### For Rewrites:\nShow the rewritten text, then a \"Changes made\" section listing which principles were applied and why.\n\n### For New Docs:\nGenerate the document applying all 10 principles. Flag any places where the user needs to provide specific data (numbers, names, dates).\n\n## Tone\nDirect but not aggressive. Confident but not arrogant. The goal is respect through clarity — honoring the reader's time by being precise.","tags":["writing","skills","aroyburman-codes","agent-skills","claude-code","claude-skills","frameworks","metrics","pm-tools","product-management","product-strategy"],"capabilities":["skill","source-aroyburman-codes","skill-pm-writing","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-frameworks","topic-metrics","topic-pm-tools","topic-product-management","topic-product-strategy"],"categories":["pm-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/aroyburman-codes/pm-skills/pm-writing","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add aroyburman-codes/pm-skills","source_repo":"https://github.com/aroyburman-codes/pm-skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 6 github stars · SKILL.md body (6,251 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:47.651Z","embedding":null,"createdAt":"2026-05-18T13:22:16.726Z","updatedAt":"2026-05-18T19:14:47.651Z","lastSeenAt":"2026-05-18T19:14:47.651Z","tsv":"'+15':267 '-12':635 '/pm-writing':87 '1':111,147,262,480,505,583 '10':142,780,942 '12k':558 '18':560 '2':126,208,231,268,291,492,507,589 '2.1':542 '2s':274 '3':276,301,499,596,623,828 '30':790 '4':370,604 '5':438,609 '500ms':275,545 '6':510 '7':568 '8':201,634,651 '9':710 'a/b/c':878 'action':38,49,107,584,627,867,888 'activ':266,338,620,631 'actual':465 'ad':615,622 'add':258,277 'affect':556 'aggress':962 'ai':414 'align':871 'allow':244 'altern':675 'alway':722,836 'ambiti':735 'answer':160 'anti':838 'anti-pattern':837 'api':690,697 'appli':12,119,931,940 'approach':183,687 'archiv':339 'arrog':966 'asap':900 'ask':228 'b':688,728,753 'background':169 'bad':168,251,404,468,529,552,614,842 'batch':696 'before/after':124 'best':60 'bluf':25,152 'bold':811 'bottom':148 'bug':566 'bullet':20,235,241 'c':734 'call':382,407 'canon':15,303,329,368,371,436 'chang':365,588,600,709,924 'choic':467 'circumst':613 'claim':581 'clariti':11,84,972 'clearer':103 'communic':31,50,98 'compar':821 'comparison':819 'concern':860 'conclus':230 'condit':610,650 'confid':963 'confirm':551 'conserv':726 'consid':677,850 'consist':374 'content':341,353 'current':206 'd7':630 'data':954 'date':335,683,884,903,957 'decid':192,666,668,673,691 'decis':227,344,653,657,682,719,775,816,873 'decre':779 'definit':324 'depend':496 'describ':129 'descript':95,741 'design':394,795 'direct':959 'disagre':289 'discuss':250 'doc':16,39,54,69,79,304,330,350,369,395,406,437,794,936 'document':8,158,939 'dr':832 'draft':68,337 'duplic':352 'effort':747 'els':320,485 'end':748 'eng':397 'engin':200,704 'enterpris':281 'estim':525,546,746 'evalu':181,695 'everi':307,569,579 'everyth':319,512 'everywher':431 'exact':311,523 'exist':115 'expect':603 'export':259,278 'extrem':10,83 'featur':260,279,380 'feedback':248 'feel':459 'first':30,154 'five':572 'fix':255,269,841,844 'flag':527,944 'flow':254,265 'follow':88 'forc':22,440 'force-rank':21,439 'form':825 'format':681,915 'forward':880 'free':640 'free-tier':639 'friday':194 'front':151 'generat':6,52,127,133,937 'get':808 'gist':810 'go':879 'goal':343,968 'good':188,261,425,479,535,557,621 'green':509 'group':443 'growth':474,500 'header':798,806 'hit':564 'honor':973 'hunt':220 'hypothesi':570,578 'idea':911 'import':452 'improv':252,263,533,619,895,897 'increas':629 'inform':358 'instead':239,294 'intellig':409 'invest':502 'key':742,813 'last':333 'latenc':257,271,540,707 'launch':400 'lead':224 'let':355 'line':149,913 'link':317,347 'list':18,233,238,445,908,927 'live':359 'll':882 'load':548 'made':659,925 'magnitud':597,636 'make':217,466,652 'mani':553 'matter':486 'mau':559 'max':830 'mayb':849 'mean':462 'measur':595 'meet':418 'mention':300 'metric':590,632,899 'mitig':865 'mode':109,110,125 'moder':729 'month':177 'much':599 'name':375,428,956 'name/team':891,893 'need':75,100,132,164,190,547,571,582,869,874,950 'never':216,354,442,447,574,758,766,820 'new':53,422,638,935 'nomenclatur':372 'note':419 'noth':484 'number':17,232,237,243,517,524,814,907,955 'onboard':253,264,616,625 'one':207,302,312,427,739,755,769,910 'one-sent':738 'open':345 'option':712,724,727,733,752,770,877 'organ':648 'outcom':592 'output':914 'over-engin':702 'owner':332,693,885 'p0':483 'p1':494 'p2':501 'p95':272,539 'paid':562 'paragraph':824,827 'part':573 'past':114,175 'patch':204 'pattern':839,843 'per':305,912 'perform':534 'pick':426 'place':362,946 'plan':172,401 'platform':477,481 'pm':2,7,34,40,58,97,145 'pm-write':1 'point':223,242 'practic':61 'prd':387 'precis':37,48,245,980 'present':717,759,767 'principl':13,121,139,143,929,943 'prioriti':24,293,446,470 'problem':761 'product':45 'project':308 'provid':723,952 'put':432 'q4':171 'qualiti':475,493 'quantifi':511 'quarter':472 'question':346,876 'rank':23,441,455,457 're':464 'read':804 'reader':167,219,785,975 'reason':757 'rebuild':197,212 'recommend':186,199,211,715,732,751,764 'reduc':538 'refer':325 'referenc':246 'relat':349 'replac':513 'request':282 'requir':708 'respect':970 'retent':495 'review':285 'revisit':680,705 'rewrit':4,92,112,117,917 'rewritten':920 'risk':862,864 'say':86,287,413,420,448 'scanner':783 'scratch':56,81,136 'search':256,270,384,391,410,415,423,649 'second':297,791 'section':926 'segment':605,643 'sentenc':155,740,756,829 'sever':176 'sharpen':73 'short':826 'shorter':104 'show':123,918 'sign':645 'signific':532,894 'skill':42 'skill-pm-writing' 'slack':403 'slow':699 'smart':383,390 'solut':765 'someon':803 'someth':364 'sourc':313 'source-aroyburman-codes' 'spec':398 'specif':863,866,875,887,902,953 'spend':789 'stabil':478,482 'stack':454 'stack-rank':453 'stakehold':721,787,890 'status':336 'step':624 'stori':802 'stream':689 'structur':26,326 'system':187,489 'tabl':817 'tell':800 'test':549 'testabl':580 'text':90,116,906,921 'thing':298,377,424,822 'think':846 'three':711 'ticket':412 'tier':641 'time':977 'titl':331 'tl':831 'tone':958 'tooltip':617,626 'top':280,835 'topic':306 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-frameworks' 'topic-metrics' 'topic-pm-tools' 'topic-product-management' 'topic-product-strategy' 'trade':744 'trade-off':743 'transform':32,43 'truth':315 'two':108,361 'uncomfort':460 'updat':334,366 'use':57,64,137,236,373,429,686 'user':65,74,85,113,128,554,563,608,642,949 'usual':730 'vagu':33,44,514,577 'various':182,889 've':179 'via':647 'visibl':654 'visual':29 'visual-first':28 'wall':904 'want':71 'websocket':701 'week':202,209,567 'whether':195 'without':762 'word':515 'write':3,35,41,46,59,77,146,575,660,781 'x':853,896","prices":[{"id":"bc132148-c78c-48c1-88fd-7db091d4f0fe","listingId":"15a39fd0-b74f-4753-bacd-ee3beffc8fc9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"aroyburman-codes","category":"pm-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:22:16.726Z"}],"sources":[{"listingId":"15a39fd0-b74f-4753-bacd-ee3beffc8fc9","source":"github","sourceId":"aroyburman-codes/pm-skills/pm-writing","sourceUrl":"https://github.com/aroyburman-codes/pm-skills/tree/main/skills/pm-writing","isPrimary":false,"firstSeenAt":"2026-05-18T13:22:16.726Z","lastSeenAt":"2026-05-18T19:14:47.651Z"}],"details":{"listingId":"15a39fd0-b74f-4753-bacd-ee3beffc8fc9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"aroyburman-codes","slug":"pm-writing","github":{"repo":"aroyburman-codes/pm-skills","stars":6,"topics":["agent-skills","ai","claude-code","claude-skills","frameworks","metrics","pm-tools","product-management","product-strategy"],"license":"mit","html_url":"https://github.com/aroyburman-codes/pm-skills","pushed_at":"2026-02-17T06:52:03Z","description":"PM workflow and product thinking skills for AI product managers. 17 structured frameworks for PRDs, metrics, strategy, writing, prioritization, and more.","skill_md_sha":"95e9dddd6d1605f14e396b5a4818fcac0887d73a","skill_md_path":"skills/pm-writing/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/aroyburman-codes/pm-skills/tree/main/skills/pm-writing"},"layout":"multi","source":"github","category":"pm-skills","frontmatter":{"name":"pm-writing","description":"Rewrite or generate PM documents with extreme clarity. Applies principles of canonical docs, numbered lists over bullets, force-ranked priorities, BLUF structure, and visual-first communication. Transforms vague PM writing into precise, actionable docs."},"skills_sh_url":"https://skills.sh/aroyburman-codes/pm-skills/pm-writing"},"updatedAt":"2026-05-18T19:14:47.651Z"}}