write-skills 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "write-skills",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Eight agent skills for writing. Each skill works alone.",
   "license": "MIT",
   "author": "adhamhaithameid",

package/skills/write-core/SKILL.md

@@ -77,6 +77,19 @@ At every depth, copy code, commands, paths, numbers, and error text exactly. Def
 
 After the draft, open `references/ai-patterns.md`. Find every pattern in the draft. Rewrite each match.
 
+## Rich styling
+
+Use styling to guide the eye. One device marks one point.
+
+- Bold: the verdict or the one key fact of the reply. Bold a word or a short phrase, never a sentence, and never twice in one reply.
+- Inline code: anything a person types or reads from a screen. Commands, paths, symbols, and error text.
+- Italics: a term at its first definition. Nothing else.
+- Headings: only when the reply has 3 or more distinct sections.
+- Lists and tables: 3 or more parallel items. Fewer items stay in the sentence.
+- Blockquote: the words of another person, quoted exact.
+- No color codes, no capital-letter shouting, no underline. Chat hosts render none of these.
+- When the host shows plain text only, write plain text. Strip the markup.
+
 ## Brief voice
 
 Level 4 runs here. Chat replies only. Saved text uses level 2 or higher.
@@ -101,6 +114,7 @@ Leave the brief voice for a security warning, an irreversible action, an order t
 - Is every sentence 25 words or fewer, with one idea?
 - Is the voice active? Are the terms stable?
 - Did you remove every pattern from `references/ai-patterns.md`?
+- Does every styling device mark a different point, at most one bold per reply?
 - Does the last sentence add a fact? Delete a recap or an offer of help.
 
 ## Safety and conflicts

package/skills/write-docs/SKILL.md

@@ -50,6 +50,22 @@ Jobs stay separate. Split the page and link, rather than mixing.
 11. One thing carries one name across the whole document.
 12. Name the real symbols, paths, flags, and commands. The codebase supplies the words.
 
+## Style the page
+
+Markdown carries the structure. Use the devices in order of strength.
+
+1. Headings carry the plan of the page. One h1, no skipped levels.
+2. Fenced code with a language tag. Use a diff fence for a change to existing code.
+3. Callouts for what the reader must act on, when the platform supports them:
+```markdown
+> [!WARNING]
+> A column rename fails the build.
+```
+4. Tables for comparisons that share 2 or more properties.
+5. Bold lead-ins only when the label names the item and the line adds new detail.
+6. Images carry alt text that states what the image shows.
+7. No color codes in the text. Markdown has none. Emphasis comes from structure, not paint.
+
 ## Revise an existing document
 
 1. Read the whole page once before you change a line.

package/skills/write-docs/references/docs-standard.md

@@ -78,6 +78,21 @@ A page can pass every rule and still read like a machine wrote it. Every sentenc
 - Take a position where the job allows it. Explanation weighs options, so say which one you favor. Reference stays neutral.
 - Trade the sterile for the particular. "Schema changes can cause issues" says nothing; "a column rename fails the build" says the thing.
 
+## Style the page
+
+Markdown carries the structure. The devices, in order of strength:
+
+1. **Headings** carry the plan of the page. One h1, no skipped levels, sentence case.
+2. **Fenced code** with a language tag. Use a `diff` fence for a change to existing code, so the reader sees the shape of the change before its content.
+3. **Callouts** for what the reader must act on: note, tip, important, warning, caution, when the platform renders them. One callout carries one instruction.
+4. **Tables** for comparisons that share 2 or more properties. Three paragraphs of parallel facts become one table.
+5. **Bold lead-ins** only when the label names the item and the line adds new detail. A label that restates the line is noise.
+6. **Images** carry alt text that states what the image shows. A diagram gets a one-line text summary beside it.
+7. **Collapsed sections** for long output the reader may skip: logs, matrices, raw data. The summary line names what sits inside.
+8. **Links** say where they go, in their own words.
+
+No color codes anywhere. Markdown carries none, and a hex code or an escape sequence in prose renders as noise. Emphasis comes from structure: the heading, the callout, the table, the fence. When a page needs more paint than structure, the page is not arranged yet.
+
 ## Claims and evidence
 
 - Write the symbols and paths that exist at this commit.

package/skills/write-pr/SKILL.md

@@ -59,6 +59,30 @@ Pick the smallest view that makes the point. One sketch is enough for most chang
 - Show a control flow change as a diff of the call tree.
 - Show a UI change with a screenshot when the environment allows it.
 
+## Formatting
+
+The host renders markdown. Use the devices it renders.
+
+- Bold the two risk verdicts: the door and the blast radius. Bold nothing else.
+- Use a diff fence for a code change. Give every fence a language tag.
+- Collapse long output behind a summary line:
+```markdown
+<details>
+<summary>Full test log, 214 lines</summary>
+
+The log text sits here, or a fenced block with a language tag.
+
+</details>
+```
+- Use the alert callouts of the host for a one-way door:
+```markdown
+> [!WARNING]
+> This change drops the old table. Run the migration before the next deploy.
+```
+- Use a table for before and after numbers.
+- Use a task list for follow-up work the reviewer must check.
+- No color codes. The host renders none.
+
 ## Rules
 
 - State what the change does first. State why second.