ZacharyZhang-NY
e74dafcd36
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
---
|
|
name: writing-clearly-and-concisely
|
|
description: Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
|
|
---
|
|
|
|
# Writing Clearly and Concisely
|
|
|
|
## Overview
|
|
|
|
Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill whenever you write prose for humans:
|
|
|
|
- Documentation, README files, technical explanations
|
|
- Commit messages, pull request descriptions
|
|
- Error messages, UI copy, help text, comments
|
|
- Reports, summaries, or any explanation
|
|
- Editing to improve clarity
|
|
|
|
**If you're writing sentences for a human to read, use this skill.**
|
|
|
|
## Limited Context Strategy
|
|
|
|
When context is tight:
|
|
|
|
1. Write your draft using judgment
|
|
2. Dispatch a subagent with your draft and the relevant section file
|
|
3. Have the subagent copyedit and return the revision
|
|
|
|
Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
|
|
|
|
## Elements of Style
|
|
|
|
William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly.
|
|
|
|
### Rules
|
|
|
|
**Elementary Rules of Usage (Grammar/Punctuation)**:
|
|
|
|
1. Form possessive singular by adding 's
|
|
2. Use comma after each term in series except last
|
|
3. Enclose parenthetic expressions between commas
|
|
4. Comma before conjunction introducing co-ordinate clause
|
|
5. Don't join independent clauses by comma
|
|
6. Don't break sentences in two
|
|
7. Participial phrase at beginning refers to grammatical subject
|
|
|
|
**Elementary Principles of Composition**:
|
|
|
|
8. One paragraph per topic
|
|
9. Begin paragraph with topic sentence
|
|
10. **Use active voice**
|
|
11. **Put statements in positive form**
|
|
12. **Use definite, specific, concrete language**
|
|
13. **Omit needless words**
|
|
14. Avoid succession of loose sentences
|
|
15. Express co-ordinate ideas in similar form
|
|
16. **Keep related words together**
|
|
17. Keep to one tense in summaries
|
|
18. **Place emphatic words at end of sentence**
|
|
|
|
### Reference Files
|
|
|
|
The rules above are summarized from Strunk's original text. For complete explanations with examples:
|
|
|
|
| Section | File | ~Tokens |
|
|
|---------|------|---------|
|
|
| Grammar, punctuation, comma rules | `02-elementary-rules-of-usage.md` | 2,500 |
|
|
| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md` | 4,500 |
|
|
| Headings, quotations, formatting | `04-a-few-matters-of-form.md` | 1,000 |
|
|
| Word choice, common errors | `05-words-and-expressions-commonly-misused.md` | 4,000 |
|
|
|
|
**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
|
|
|
|
## AI Writing Patterns to Avoid
|
|
|
|
LLMs regress to statistical means, producing generic, puffy prose. Avoid:
|
|
|
|
- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
|
|
- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
|
|
- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
|
|
- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
|
|
- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
|
|
|
|
Be specific, not grandiose. Say what it actually does.
|
|
|
|
For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
|
|
|
|
## Bottom Line
|
|
|
|
Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.
|