writing-clearly
Skill3 starsChanged 19 days agoMITView on GitHub
Help PMs write clear, concise prose for PM artifacts. Use for PRDs, status updates, Slack posts, emails, and documentation.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- theyoungastronauts/polaristheir own version, first seen Nov 1, 2026
- fockus/writing-clearlytheir own version, first seen Jul 27, 2026
- ianklassen/ai-pm-systemword for word, first seen Apr 12, 2026
Other versions3 projects use a version of this.
Word for word · 1
- ianklassen/ai-pm-system★ 1100% same
Edited · 0
None found.
Wrote their own version · 2
- fockus/writing-clearly★ 8same name
- theyoungastronauts/polaris★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- company-product-signalsSkill
- company-researcherSkill
- company-strategySkill
- pm-os-onboardingSkill
- brainstormingSkill
- continual-learningSkill
- decision-loggerSkill
- eval-briefSkill
- exec-communicatorSkill
- experiment-designerSkill
- experiment-writeupSkill
- knowledge-updaterSkill
- launch-postSkill
- launch-readinessSkill
- meeting-to-actionsSkill
- one-pagerSkill
- pptx-creatorSkill
- prd-writerSkill
- stakeholder-updateSkill
- strategy-connectorSkill
- what-ifSkill
- working-backwardsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
When asked "help me make this clearer" or "tighten this up"
- Distinctive: line 29
Put the conclusion or ask first
- Distinctive: line 30
Don't bury the lead in the last paragraph
- Distinctive: line 33
Prefer short words over long (use vs.
- Distinctive: line 34
Prefer active voice (we will ship vs.
- Distinctive: line 38
Use numbers, dates, names instead of "soon," "many," "several"
- Distinctive: line 42
Use headers, bullets, and short paragraphs
- Distinctive: line 47
Remove filler (e.g., "in order to" → "to")
- Distinctive: line 49
If a sentence doesn't add value, cut it
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Clearly
Help PMs write clear, concise prose for PM artifacts. Applies principles of plain language, structure, and scannability to make communications effective and easy to act on.
When to Use
- Writing or editing a PRD
- Drafting status updates or stakeholder comms
- Composing Slack posts or emails
- Creating documentation or runbooks
- When asked "help me make this clearer" or "tighten this up"
Process / Template
1. Identify the Artifact and Audience
- What are you writing? (PRD, update, post, doc)
- Who will read it? (engineers, leadership, customers)
- What do they need to do? (decide, build, understand, act)
2. Apply Clear Writing Principles
Lead with the main point
- Put the conclusion or ask first
- Don't bury the lead in the last paragraph
Use plain language
- Prefer short words over long (use vs. utilize, help vs. facilitate)
- Prefer active voice (we will ship vs. it will be shipped)
- Cut jargon unless the audience expects it
Be specific
- Use numbers, dates, names instead of "soon," "many," "several"
- Replace vague terms with concrete ones
Structure for scannability
- Use headers, bullets, and short paragraphs
- One idea per paragraph
- Front-load key info in each sentence
Cut ruthlessly
- Remove filler (e.g., "in order to" → "to")
- Remove redundancy
- If a sentence doesn't add value, cut it
3. Use the Right Format
| Artifact | Key Moves |
| PRD | Clear problem statement, explicit requirements, scannable sections |
| Status update | TL;DR first, bullets, metrics, explicit asks |
| Slack/email | Short paragraphs, one ask per message |
| Doc/runbook | Step-by-step, headers, examples |
4. Edit in Passes
- Pass 1 — Structure: does the order make sense?
- Pass 2 — Clarity: can a reader understand it in one pass?
- Pass 3 — Brevity: what can be cut?
5. Validate
- Can the reader answer: What? Why? What do I do?
- Would a busy executive get it in 2 minutes?
- Are there ambiguous pronouns or missing context?
Output
Clear, concise prose that:
- Communicates the intended message
- Is easy to scan and act on
- Respects the reader's time
- Fits the format (PRD, Slack, email, doc)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.