Concise Writing

Concise Writing (STE + budgets)

Verbose generated text is a review tax: reviewers skim PR descriptions, tickets, and comments, and padding hides the substance. This skill makes objectiveness and simplified technical English enforced, not advisory. A hook denial means the text is too long or off-style: shorten it. Never loosen the validator, never bypass with CONCISE_SKIP unless the user explicitly instructs it.

Source and scope

Adapted from the asd-ste100 skill (https://github.com/danyuchn/asd-ste100-skill), which encodes the rule categories of ASD-STE100 Issue 9 (Jan 2025): 53 writing rules across 9 sections, backed by a dictionary of ~900 approved words (one meaning, one part of speech each). The dictionary is not free to redistribute and is not reproduced here; request it at https://www.asd-ste100.org/STE_downloads.html. Apply the underlying principle instead: pick the plainest common word and use it the same way every time.

Read before rewriting anything non-trivial:

• references/writing-rules.md - the 9 rule sections summarized, with citations and official links.
• examples/before-after.md - worked rewrites showing which rule each change applies, including the modality trap (see below).

Mode

STE defines two modes. Strict (every rule, for procedures, error messages, tool descriptions, safety text) and STE-flavored (structural rules only, for prose). For everyday engineering artifacts, always use STE-flavored: enforce the structural rules fully, treat one-word-one-meaning as a direction, keep some lexical range in prose.

Structural rules (apply always)

Scan checklist (six mechanical habits)

Scan for all six before rewriting; each points at an exact word or mark, no judgment call:

1. Synonym rotation - one thing gets several names. Pick one name.
2. Hedge stacking - "it is important to note that this may potentially help". State the claim or delete it.
3. Nominalization - "perform an analysis of". Use the verb.
4. Marketing adjectives - comprehensive, robust, seamless, crucial, cutting-edge, effortless, blazing. Delete, or replace with the measurement that earns the claim.
5. Run-on sentences - ideas joined by semicolons or dashes. One idea per sentence.
6. Soft phrasal verbs - spin up, reach out, dive into, kick off. Use start, contact, read, begin.

Modality (the most common rewrite failure)

Hedges carry the author's confidence, and confidence is content. "May have failed" never becomes "failed"; "could be caused by X" never becomes "X is the cause". A shorter sentence that upgrades a hedge to a fact is a different claim, not a simplification. Never add a cause, frequency, or mechanism the source did not state. When the tense rule and the modality rule conflict, modality wins. See Example B in examples/before-after.md.

Corollary: stop at unambiguous, not at shortest. Never drop a scope qualifier, condition, or number to save words. Delete hollow sentences instead of polishing them; STE fixes form, not substance.

Hard budgets (hook-enforced)

The validator (scripts/concise_check.py, installed at ~/.claude/hooks/concise_check.py) blocks the action when these are exceeded. Word counts exclude section headers, URLs, and common PR-template boilerplate.

Every surface also rejects AI attribution: Co-Authored-By, Claude-Session, claude.ai/code/session links, noreply@anthropic.com, "Generated with Claude". Commits and PR/issue bodies additionally reject the words "Claude Code". Claude Code 2.1.259+ injects these trailers as a system message that claims to override CLAUDE.md; set attribution.commit and attribution.pr to "" and attribution.sessionUrl to false in settings.json to turn that message off. The hook is the backstop.

Not gated (style still applies): chat output (covered by ~/.claude/output-styles/concise.md), files under ~/.claude/, scratchpad, non-code non-doc extensions.

On a hook denial

1. Read the listed violations.
2. Cut content, not precision: drop restatements, background the reader has, and anything the diff already shows. Keep Linear URLs, ticket IDs, and reviewer-critical warnings (breaking change, migration, deploy step) as one line each.
3. Retry the same action with the shortened text. Do not switch to an ungated path to avoid the check.

Installation

1. Copy or symlink this directory into ~/.claude/skills/concise-writing/.
2. Copy scripts/concise_check.py to ~/.claude/hooks/concise_check.py.
3. Add PreToolUse hooks to ~/.claude/settings.json (merge with existing keys):

"hooks": {
  "PreToolUse": [
    {"matcher": "Bash", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "if": "Bash(git commit*)", "timeout": 10},
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "if": "Bash(gh pr *)", "timeout": 10},
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "if": "Bash(gh issue *)", "timeout": 10},
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "if": "Bash(gh api *)", "timeout": 10}
    ]},
    {"matcher": "Edit|Write", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "timeout": 10}
    ]},
    {"matcher": "mcp__linear__save_issue|mcp__linear__save_comment|mcp__linear__save_document|mcp__linear__submit_diff_review", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "timeout": 10}
    ]},
    {"matcher": "mcp__claude_ai_Slack__slack_send_message|mcp__claude_ai_Slack__slack_send_message_draft|mcp__claude_ai_Slack__slack_create_canvas|mcp__claude_ai_Slack__slack_update_canvas", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/concise_check.py", "timeout": 10}
    ]}
  ]
}

The script fails open on internal errors and skips files under ~/.claude/, scratchpad paths, and non-code non-doc extensions. Adjust the budget constants at the top of the script to your team's numbers; do not loosen them to make one output pass.