Add Precise Technical Writing skill to the 7Factor catalog - #10
Add Precise Technical Writing skill to the 7Factor catalog#10goneflyin wants to merge 11 commits into
Conversation
The skill was added without a corresponding entry under Available Skills. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
231 lines -> 131. The repo's write-a-skill checklist caps SKILL.md at 100 lines; the remainder is two mapping tables that every run consumes, so disclosing them to a sibling file would cost more than it saves. - Reinstate "gears" as the leading word. The four modes are one style at four compression ratios, so order them on that axis and give the dial a default (start in 2) instead of a per-artifact lookup. - Collapse seven artifact enumerations (58 entries, one taxonomy) into a single intent table and a single artifact fallback table. - Delete Anti-Patterns. Eight prohibitions, six of which restated a positive rule; the two live ones became rows in the artifact table. Steering by prohibition names the behavior it bans. - Flip the remaining 14 "Do not" bullets to positive form. - Drop no-op rules the model already follows by default. - Restore the ~20-word sentence bound, which makes gear 3 checkable. - Rename the `reference` intent to `look-up`; it collided with the `reference` mode. - Give the workflow a checkable completion criterion: every output claim traces to an input claim at equal or weaker strength. - Add "Refining text that already exists" — rebuild from an extracted claim list, since a rewrite keys off the prose it reads. - Attribute ASD-STE100 to non-native readers, not aircraft maintenance. - Note prose-linter enforcement for style drift. - Halve the description; it renamed one branch ten times. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Concision is instrumental to precision, not the goal. ASD-STE100 rule 4.2 forbids shortening by omission, and the skill's own claim-safety rule already outranks concision — so the old name pointed at the property the skill subordinates. Gear 4 now requires a Sources field instead of listing it as optional. A reference doc describes something it is not connected to; the path is what lets a reader re-check it. Dropped the Verification field: re-checking a doc against code is a separate concern from wording it. Frontmatter: author is not in the agentskills.io specification, so move it under metadata as a single string. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mariobrubio
left a comment
mariobrubio
left a comment
There was a problem hiding this comment.
Review: Add Concise Technical Writing skill
Summary: Solid concept and genuinely useful rules, but the skill doesn't follow this repo's own authoring guide (.agents/skills/write-a-skill), and the writing itself is more repetitive than a "concise writing" skill should tolerate. Recommend addressing the length/redundancy and missing example before merging.
Findings, most significant first
1. Length — 231 lines vs. the repo's own 100-line guideline
write-a-skill's review checklist requires SKILL.md under 100 lines; this file is 231 — over double, and longer than either existing skill (claude-usage-report 174, mentor 102). The content has clearly separable domains (five writing modes, an artifact-mapping table), which write-a-skill's own "When to Split Files" rule calls out as exactly the case for a REFERENCE.md. Recommend moving the per-mode rule lists there and keeping SKILL.md to the classifier, workflow, and pointers.
2. Redundant artifact-to-mode mapping
Each mode's "Good for:" list (e.g., engineering → PR descriptions, review replies…) and the separate "Common Artifact Mapping" section encode the same mapping in two directions. Pick one. This is a direct instance of the rule the skill itself teaches ("If it is possible to cut a word out, always cut it out") — cutting the duplicate section would meaningfully shrink the file toward finding #1's target.
3. No concrete example
There's no before/after text anywhere — no "Quick start" section at all, despite write-a-skill's template making that section first and its checklist requiring "concrete examples included." A style skill built on subjective judgment calls (what counts as "filler," where controlled mode's line is) needs at least one worked example per mode to be usable rather than aspirational.
4. "Embedded Use Contract" is unverified but stated as fact
The section proposes that other skills can depend on this one via a quoted instruction snippet. Nothing in AGENTS.md or any existing skill in this repo documents or exercises cross-skill dependency this way — it's a new, untested mechanism, presented without the Unknown:/Assumption: labeling the skill's own "Claim Safety" section requires for unverified claims. Either demonstrate it working (e.g., wire it into one existing skill) or mark it as a proposal.
5. author frontmatter breaks convention
Neither mentor nor claude-usage-report carries an author field, and this one embeds a personal name and work email. Not wrong, but worth a maintainer call on whether that's the intended pattern for this catalog before it becomes precedent.
6. README not updated
README.md's "Available Skills" list still only shows mentor and claude-usage-report. Add the new skill there for consistency with how the catalog documents itself.
7. Minor: description doesn't follow the guide's own template
write-a-skill specifies "first sentence: what it does, second sentence: Use when…"; this description opens directly with "Use when…" with no lead sentence stating the capability. Small, but easy to fix while touching the file anyway.
Not a concern
Confirmed marketplace.json only lists plugin-requiring skills (claude-usage-report, which ships a hook) — mentor isn't listed either, so omitting concise-technical-writing there is correct, not a gap.
🤖 Generated with Claude Code
Makes the Hacker News critique falsifiable instead of arguable. Four arms — no instruction, hsaliak's one-line prompt, Orwell's six rules, the full skill — over six tasks, one per gear. Two tasks carry the experiment. incident-reply reproduces the failure atoav found in the reference skill's own example output: an agent told to simplify language added internal detail and a customer commitment that were not in the source. Its input holds an unconfirmed cause, an internal hostname, and no agreed date. tradeoff tests the opposite error, over-application: its input is unresolved disagreement that controlled language would flatten. Scoring keeps style and fidelity apart and never sums them. Length is reported, never scored: ASD-STE100 rule 4.2 forbids shortening by omission, and the thread's own top exchange shows a two-word cut changing a meaning. Judging is blind — arm labels stripped, order shuffled on a fixed seed. Known confound, documented rather than hidden: claude --bare is the only mode that skips user-memory discovery and it needs ANTHROPIC_API_KEY, so on an OAuth-only machine every arm carries the operator's global CLAUDE.md. Verified by probing each configuration for a string unique to that file. Contamination is constant across arms, so relative ordering holds and absolute numbers do not. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Found by reading the outputs behind findings that fired identically across
all four arms. A rule that flags every arm is measuring the rule.
- required patterns could not match through markdown emphasis, so a real
"**Sources:**" field read as omitted on every arm that used bold.
- must_hedge fired whenever hedge markers were absent, but they are also
absent when the claim itself is absent. Hardening and omission are
opposite outcomes; each must_hedge rule now declares presence markers and
they are counted separately.
- term groups holding a substring pair ("pool" inside "connection pool",
"key" inside "signing key") flagged drift on every output by
construction. Replaced, and validate_task now rejects the whole class.
- score.py accepted half-written files from an in-flight generation and
reported every hedge as missing. It now skips anything under 20 words.
Also: the incident-reply hedge rules take absent_ok, because for a public
status page saying nothing about an unconfirmed cause is restraint, not
failure. The measured failure is raising the claim and stating it firmly.
…nvention
The eval found the skill fabricating more than the arms without it. Blind
judging put it 5-12 against baseline, a one-line prompt, and Orwell's rules,
and 9 of the 12 losses gave the same reason. Three fabrications, each checked
against the task input by hand:
tradeoff "**Date:** 2026-08-03" input has no date
reference-summary "exactly-once delivery" input has a dedupe table
runbook "if not present, add it now" conflicts with the
documented recovery path
All three break the skill's own rule against adding what the source lacks,
and the runbook one invents a procedure that contradicts the real recovery.
Diagnosis: "name each error state", "use these fields", and "always include
Sources" each ask for a slot. With no source data for the slot, filling it
means inventing, and nothing said an empty slot was allowed. The arms with no
completeness rules had nothing pushing them to fill anything. The skill's only
deterministic win — the sole arm to emit a Sources field — came from the same
pressure as its losses.
So claim safety now outranks every structural rule rather than only
concision, an unsupported field is written as Unknown: instead of filled, and
the three rules ask the writer to look for a fact rather than supply one.
The skill did win incident-reply 3-0, the task built for claim safety, where
the other arms hardened the unconfirmed cause and leaked internal detail. The
deterministic scorer missed that entirely; only the judge saw it.
Patched skill moves 5-12 to 12-12 under blind judging, which is both a real gain and a dead heat with every arm including the one-line prompt. Against the original 231-line version it is 3-3, so the refactor is a wash on judged quality. Two results argue against the refactor: - The original produces the tightest prose in the field (18.5% of sentences over 20 words against the refactor's 33.1%, median 11.8 against 15.0), beating Orwell too. Pruning its restated style rules as duplication also removed reinforcement. - Only one of three fabrications is fixed. Both versions still write "exactly-once delivery" for what the source describes as a dedupe table, so that one is not the completeness pressure diagnosed in run 1 — the original has no mandatory-field rule and produces it anyway. Gear 3's "keep precise software terms" is the likely cause: a canonical term asserts the guarantees it carries. Competitor outputs deliberately not regenerated, so both skill versions face an identical opponent set and the comparison is paired.
goneflyin
changed the title
2 participants
Creates a skill to assist claude in writing clean, precise documents and comments. Greatly improves the AI-slop nature of so much of what Claude writes.
Derived from the idea of using ASD STE-100 for better technical writing.
Note: Some of said they get similar or better results simply by using Orwell's 6 rules of writing:
1 Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it out.
4. Never use the passive where you can use the active.
5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.
Caveat
These kinds of skills are notoriously hard to validate with hard data. Using an eval harness that it created and spent all my 7F tokens for the 5h period in about 30 mins, it concluded that it was better in a few ways but not at all in many others.
At the same time, the ASD STE-100 viral talk is happening for a reason -- people do see a difference. The questions seem to come down to:
I'm sure this will get better over time, but for now, this is something that I've found can help. If it doesn't, we can iterate on it or take it down. But I think it's worth circulating and getting some other experience with it.