edit-for-readability

Name: edit-for-readability
Author: testdouble

122stars12forks

How to install edit-for-readability?

testdouble/han/edit-for-readability

$npx -y skills add testdouble/han --skill edit-for-readability

Installs into the current project.

Summary

Applies Han's shared Human-Readable Output Standard to a target you already have — a file on disk, text pasted into the prompt, or a draft already produced in the conversation — by dispatching the readability-editor to rewrite its prose so the main point comes first, headings are

Files · 1

View on GitHub

SKILL.md

1	# Edit for Readability
2
3	Take a target the user already has and rewrite its prose against the shared readability standard, preserving every fact. The judgment-heavy rewrite belongs to the `han-core:readability-editor` agent; this skill's job is to resolve what the target is, dispatch the editor over it, and deliver the result.
4
5	## Operating principles
6
7	- This is the standalone readability pass. The readability standard applies at generation time, so synthesis skills (research, project-documentation, investigate, code-review, and the rest) already bake it into their own output. This skill exists for the gap the standard names explicitly: a file or draft that was written or hand-edited outside one of those skills, and so was never checked against the standard. Reach for it on an existing target, not as a step inside another skill.
8	- Fidelity outranks readability on every conflict. Every claim, quantity, named entity, and stated condition or qualifier in the target survives the rewrite with its precision intact. The editor enforces this and returns a fact-preservation ledger; the skill's job is to pass the whole target through and surface that ledger, never to let a fact be dropped for the sake of a smoother sentence.
9	- Prose only. The editor rewrites prose regions and leaves code fences, diagram bodies, rendered markup, and citation identifiers (`A1`, `[F5]`, and the like) byte-for-byte unchanged. Do not ask it to touch anything else.
10	- The editor holds the standard. Do not restate the six rubric criteria here or inline the rule text into the dispatch. Point the editor at the rule file and let it apply the current standard, so this skill never drifts from `readability-rule.md`.
11
12	## Step 1: Resolve the target and the reader
13
14	Determine which kind of target the request names, because the rest of the workflow depends on it. Read the user's request and the conversation, and classify the target into exactly one of:
15
16	\| Target kind \| How you know \| What the target is \|
17	\|---\|---\|---\|
18	\| A file on disk \| The user named a path, or the context points at one obvious file \| That file, edited in place \|
19	\| Pasted text \| The user included the text to edit directly in the prompt \| Verbatim copy of that text \|
20	\| A draft in the conversation \| The user says "the draft above," "what you just wrote," or similar \| Verbatim copy of that draft \|
21
22	If more than one candidate fits, or you cannot tell which file the user means, stop and ask the user which target to edit before doing anything else. Never guess at a file to overwrite.
23
24	For a file target, confirm the file exists and read it. Use `Glob`/`Grep` to resolve a partial name to a concrete path. If the named file does not exist or is empty, stop and tell the user rather than editing the wrong file.
25
26	For a pasted-text or conversation-draft target, write the content verbatim to a new scratch file (for example `readability-target.md` in the session scratch directory or the working directory) so the editor has a file to rewrite in place. Copy it exactly — do not clean it up first, because pre-editing would rob the editor of the original and break the fact-preservation check.
27
28	Also settle the reader frame: default to a capable reader who did not do this work and lacks the author's context. If the user names a specific reader (an engineer implementing a fix, a PR reviewer, a non-technical stakeholder), carry that reader to the editor instead so the technical specifics that reader needs are kept.
29
30	## Step 2: Confirm before rewriting a file in place
31
32	If the target is a file on disk (not a scratch copy of pasted text or a conversation draft), tell the user which file will be rewritten in place and that every fact is preserved, then get a go-ahead before dispatching. Always confirm before overwriting a user's file BECAUSE the in-place rewrite is the one action here th

People who liked this also viewed

6 picks

Type

edit-for-readability

122stars12forks

View on GitHub

How to install edit-for-readability?

testdouble/han/edit-for-readability

$npx -y skills add testdouble/han --skill edit-for-readability

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Edit for Readability
2
3	Take a target the user already has and rewrite its prose against the shared readability standard, preserving every fact. The judgment-heavy rewrite belongs to the `han-core:readability-editor` agent; this skill's job is to resolve what the target is, dispatch the editor over it, and deliver the result.
4
5	## Operating principles
6
7	- This is the standalone readability pass. The readability standard applies at generation time, so synthesis skills (research, project-documentation, investigate, code-review, and the rest) already bake it into their own output. This skill exists for the gap the standard names explicitly: a file or draft that was written or hand-edited outside one of those skills, and so was never checked against the standard. Reach for it on an existing target, not as a step inside another skill.
8	- Fidelity outranks readability on every conflict. Every claim, quantity, named entity, and stated condition or qualifier in the target survives the rewrite with its precision intact. The editor enforces this and returns a fact-preservation ledger; the skill's job is to pass the whole target through and surface that ledger, never to let a fact be dropped for the sake of a smoother sentence.
9	- Prose only. The editor rewrites prose regions and leaves code fences, diagram bodies, rendered markup, and citation identifiers (`A1`, `[F5]`, and the like) byte-for-byte unchanged. Do not ask it to touch anything else.
10	- The editor holds the standard. Do not restate the six rubric criteria here or inline the rule text into the dispatch. Point the editor at the rule file and let it apply the current standard, so this skill never drifts from `readability-rule.md`.
11
12	## Step 1: Resolve the target and the reader
13
14	Determine which kind of target the request names, because the rest of the workflow depends on it. Read the user's request and the conversation, and classify the target into exactly one of:
15
16	\| Target kind \| How you know \| What the target is \|
17	\|---\|---\|---\|
18	\| A file on disk \| The user named a path, or the context points at one obvious file \| That file, edited in place \|
19	\| Pasted text \| The user included the text to edit directly in the prompt \| Verbatim copy of that text \|
20	\| A draft in the conversation \| The user says "the draft above," "what you just wrote," or similar \| Verbatim copy of that draft \|
21
22	If more than one candidate fits, or you cannot tell which file the user means, stop and ask the user which target to edit before doing anything else. Never guess at a file to overwrite.
23
24	For a file target, confirm the file exists and read it. Use `Glob`/`Grep` to resolve a partial name to a concrete path. If the named file does not exist or is empty, stop and tell the user rather than editing the wrong file.
25
26	For a pasted-text or conversation-draft target, write the content verbatim to a new scratch file (for example `readability-target.md` in the session scratch directory or the working directory) so the editor has a file to rewrite in place. Copy it exactly — do not clean it up first, because pre-editing would rob the editor of the original and break the fact-preservation check.
27
28	Also settle the reader frame: default to a capable reader who did not do this work and lacks the author's context. If the user names a specific reader (an engineer implementing a fix, a PR reviewer, a non-technical stakeholder), carry that reader to the editor instead so the technical specifics that reader needs are kept.
29
30	## Step 2: Confirm before rewriting a file in place
31
32	If the target is a file on disk (not a scratch copy of pasted text or a conversation draft), tell the user which file will be rewritten in place and that every fact is preserved, then get a go-ahead before dispatching. Always confirm before overwriting a user's file BECAUSE the in-place rewrite is the one action here th

People who liked this also viewed

6 picks

Type