be-concise
Reshape prose so a scanning reader gets the point: bottom line first, no more words than the meaning needs, structure that survives scanning, factual tone. Two modes. Invoked bare it sets a standing posture for everything written afterwards; given any target it reshapes that text and reports before and after word counts. Never drops a decision, number, ask, error or warning, and never edits an already-posted record in place unless told to. Use when: 'write this for the PO', 'shorten this ticket', 'make this scannable', 'bottom line first', 'nobody will read this', 'rewrite this PR description for reviewers', or before writing anything a person reads in a tracker, a pull request, a doc, or a status update. Not for: in-flight chat and code terseness (discipline:tighten-your-output), word-level trimming of a repo .md (docs-hygiene:compress), restructuring without shortening (adhd:clarify), or doc genre and language standards at authoring time (docs-hygiene:write-for-humans).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- metadata
- { "summary": "Reshape prose for a scanning reader. Bottom line first, about half the words", "workflow-stage": "anytime" }
- description
- Reshape prose so a scanning reader gets the point: bottom line first, no more words than the meaning needs, structure that survives scanning, factual tone. Two modes. Invoked bare it sets a standing posture for everything written afterwards; given any target it reshapes that text and reports before and after word counts. Never drops a decision, number, ask, error or warning, and never edits an already-posted record in place unless told to. Use when: 'write this for the PO', 'shorten this ticket', 'make this scannable', 'bottom line first', 'nobody will read this', 'rewrite this PR description for reviewers', or before writing anything a person reads in a tracker, a pull request, a doc, or a status update. Not for: in-flight chat and code terseness (discipline:tighten-your-output), word-level trimming of a repo .md (docs-hygiene:compress), restructuring without shortening (adhd:clarify), or doc genre and language standards at authoring time (docs-hygiene:write-for-humans).
- argument-hint
- [target]
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 2
- 参考文档reference/doctrine.md13.7 KB
- 参考文档reference/sources.md12.6 KB
03 SKILL.md 正文
Be concise
Two modes
Bare invocation sets a standing posture. Apply the four properties to all reader-facing prose you write for the rest of the session. Say once that the posture is on, then stop narrating it.
With a target, reshape that text. The target is anything your tools can resolve: pasted text, a file, a URL, a pull request, a tracker item. Look instead of asking which kind it is.
The four properties
Read reference/doctrine.md for the rules and their
thresholds. In brief:
- The point comes first. The conclusion, ask, or status opens the text, so a reader who stops after one sentence still knows what you needed.
- No more words than the meaning needs. Aim at about half a first draft. Cut expletives, intensifiers, redundancy, and clauses that add nothing.
- Structure that survives scanning. Informative headings, one idea per paragraph, lists where a reader scans for facts.
- Factual tone. No hype, no selling, no filler.
Properties 2 and 4 apply to any prose, including text only an agent reads. Properties 1 and 3 are for human readers only.
Readers scan, which is why these rules exist. The evidence for the size of the
effect is one unreplicated 1997 study of 51 users; say so when it comes up
rather than presenting it as settled. Details and sources: the doctrine file
and reference/sources.md.
What never gets cut
Completeness is a floor, not a trade-off. Never drop, in any mode:
- A decision, a number, a date, a name, or an explicit ask.
- An error, a warning, or anything about a destructive or irreversible action.
- A caveat that changes what the reader would do.
- A structural contract the destination imposes. A pull-request body that needs a closing keyword line and four named sections still has them afterwards.
When brevity and completeness conflict, put the bottom line first and keep the full record below it or one link away. Never resolve it by deleting.
Infer reader and destination
Settle three things from the text in front of you; ask only when it cannot tell you:
- Who reads this. An executive skimming for status needs a different first sentence than a reviewer acting on specifics.
- Where it lands. A tracker comment, a pull-request body, a changelog entry and a README each carry conventions, sometimes a hard contract.
- What must survive. The completeness floor, plus anything the destination's own gate requires.
Apply the general doctrine; keep no fixed table of destinations, which would go stale and answer only the cases someone listed.
Never edit a posted record in place
If the text is already published (a ticket, a comment, a pull request, anywhere a reader may have seen it), do not overwrite it. Offer the reshaped version and let the user decide, because overwriting destroys the audit trail. Edit in place only on an explicit instruction to.
Guard the meaning
When the original has more than three paragraphs or more than 250 words, verify the rewrite with a fresh-context semantic diff before handing it over. Count the original's paragraphs and words before you start. Dispatch a subagent that did not write the rewrite, give it the before and after text, and have it report only:
- SEMANTIC LOSS. Something the original stated that the rewrite does not.
- DROPPED DECISION, NUMBER, OR ASK. Content that survived as words but moved out of the place a reader would look, or vanished when two paragraphs merged.
- AMBIGUITY. Something the rewrite made less determinate.
- FALSE POSITIVE. A flagged item that is actually fine.
Every finding cites the exact text. Restore anything confirmed lost, then hand over. For an original within both limits, such as a four-line comment, show the before and after inline instead; a subagent round-trip costs more than the reader's whole message.
Before deciding, run
bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin writing --skill be-concise
and copy its line into the result
(levels).
standard is the rule above; strict runs the semantic diff on every rewrite, whatever its size.
Under light, and off, which acts as light here, dispatch no subagent and never run the diff
yourself in its place: show the before and after, write verification: skipped (<level>), and
say the meaning was not independently checked.
Report the result
End every reshape with the before and after word counts as plain counts, never a percentage claim.
Boundary
- Never shortens by dropping content. Density is the goal, not length. A rewrite that loses a decision has failed even if it halves the word count.
- In-flight chat and code terseness:
discipline:tighten-your-outputwhen thedisciplineplugin is enabled. - Word-by-word trimming of repo markdown:
docs-hygiene:compresswhen thedocs-hygieneplugin is enabled. - Does not restructure a dense message without shortening it (chunking a
decision-heavy artifact one decision at a time), even when asked to and even
when no route is available. That is
adhd:clarifywhen theadhdplugin is enabled. - Does not reshape agent-facing instruction prose (a skill body, a rules
file, any text a model follows), even when asked to and even when no route is
available. That is
docs-hygiene:write-for-agentswhen thedocs-hygieneplugin is enabled. Take properties 2 and 4 there and leave 1 and 3 behind. - Documentation genre and language standards (Diataxis type, terminology,
controlled language at authoring time):
docs-hygiene:write-for-humanswhen thedocs-hygieneplugin is enabled. - AI-writing tells (em dashes, chatbot phrasing, the rest of that catalog):
ai-slop:auditwhen theai-slopplugin is enabled. This skill inherits that plugin's config and adds no punctuation rule of its own. - No detector script, no CI gate. Judgment plus the word count.
Gotchas
- Halving the words is not the goal on text that is already dense. The target is a first draft. Re-running this on its own output cuts meaning.
- Lists are for facts a reader scans, not reasoning a reader follows. Bulleting an argument breaks its thread. Bold a few keywords per screen at most, and never bold a restatement of the line it sits on.
- Bottom line first means first, not instead. A reader who needs the detail is not served by a summary that hides it.
- Do not report a percentage improvement. The word-count delta is measurable; a usability claim about this rewrite is not.
Attribution
The rules paraphrase, never copy, Nielsen Norman Group's research on concise,
scannable and objective web writing, GOV.UK content design, the US federal
plain-language guidelines, Google's and Microsoft's style guides, and BLUF.
Each carries a drift stamp in reference/sources.md.
No upstream article text is vendored here.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').