write-skills 0.0.0-stage → 0.1.0

package/skills/write-comments/references/ste.md

@@ -0,0 +1,82 @@
+# Simplified Technical English rules
+
+## Purpose
+
+Write prose that a non-native English reader understands at first read, without guessing. These rules follow the Issue 9 principles of ASD-STE100.
+
+## Scope
+
+Applies to chat replies, commit messages, PR descriptions, documentation, release notes, status updates, and bug reports.
+Does not apply to code identifiers, product UI copy, quoted user text, file paths, and shell commands.
+
+## Writing rules
+
+1. Keep sentences short. Use 20 words or fewer in instructions. Use 25 words or fewer in descriptive text.
+2. Write one instruction, or one topic, per sentence.
+3. Use the active voice. Use the passive voice only when the agent is unknown. Name the agent when you know it.
+4. Write one topic per paragraph. Use 6 sentences or fewer per paragraph.
+5. Use simple verb forms only: simple present, simple past, simple future, imperative, infinitive.
+6. Do not use the "-ing" form of a verb unless it is a technical noun.
+7. Use each word with one meaning only.
+8. Do not use multi-word nouns with more than three words.
+9. Do not use idioms, slang, metaphors, jokes, or cultural references.
+10. Do not use double negatives. Write one clear negative, or write the positive statement.
+11. Do not use contractions. Keep the articles "the" and "a" in sentences.
+12. Use the same word for the same thing. Do not alternate synonyms.
+13. Use vertical lists for data or steps with more than two items.
+14. In procedures, start each step with the command verb. Put warnings before the step.
+15. Split complex text into more sentences. Do not omit the subject or the article to make a sentence shorter.
+
+## Word guidance
+
+- Prefer the shortest common word: "use", not "utilize". Write "start", not "initiate". Write "before", not "prior to".
+- Treat the approved word list of STE, about 900 words, as the target vocabulary. Approximate it with common English words, one sense each.
+- Technical terms are allowed. Define a technical term on first use.
+- Do not invent a new term for a thing you already named.
+
+## Examples
+
+Commit message, before and after:
+
+```text
+Before: "Refactored auth layer to leverage modern async patterns, kicking
+off the long-overdue cleanup of the legacy session nightmare."
+After: "Make the auth module use async functions. Remove the old session
+code. Do not migrate session data. See ticket ABC-123."
+```
+
+Status update, before and after:
+
+```text
+Before: "We're currently experiencing some issues with the deployment
+pipeline, which has been acting up since this morning."
+After: "The deployment pipeline failed at 09:15. The build step gave error
+E403. We are investigating the cause. The next update comes at 14:00."
+```
+
+Bug report, before and after:
+
+```text
+Before: "Users can't seem to export their reports whenever the dataset is
+particularly large. It just silently fails without any error."
+After: "Export fails for datasets larger than 50000 rows. The app shows no
+error. To reproduce: load the sample dataset, click Export, wait 60 seconds."
+```
+
+## Conflicts with other styles
+
+When another active style conflicts with these rules, these rules win for prose. A brief style may shorten sentences further. It keeps every fact, negation, and number.
+
+## Compliance check
+
+- Are all sentences 25 words or fewer?
+- Does each sentence give one instruction or one topic?
+- Is the voice active, except where the agent is unknown?
+- Are there no idioms, jokes, metaphors, contractions, or double negatives?
+- Is every technical term defined on first use, and is each term stable?
+
+## Sources
+
+- https://asd-ste100.org/
+- https://en.wikipedia.org/wiki/Simplified_Technical_English
+- https://github.com/danyuchn/asd-ste100-skill

package/skills/write-commit/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: write-commit
+description: >
+  Use when the agent writes a commit message, or when the user asks for
+  commit text, a commit subject, or a commit body.
+---
+
+# Write commit
+
+One change, one commit, one message. The message gives the intent. The diff already shows the what.
+
+## Read first
+
+1. Read the staged diff. A commit message describes the staged change, not the plan.
+2. Read the history with `git log --oneline -15`. Match the type words, the scope style, and the capitalization of the repo.
+3. Read the contribution guide when the repo has one. It wins on format.
+
+## Subject
+
+- Format: `type(scope): summary`. The scope part is optional.
+- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`.
+- Imperative mood: "add", not "added" or "adds".
+- Fifty characters or fewer when possible. Seventy-two is the hard cap. No trailing period.
+
+## Body
+
+Skip the body when the subject says it all. Add a body only for:
+
+1. A why the diff cannot show.
+2. A breaking change and its migration path.
+3. A linked issue or a follow-up.
+
+Always add a body for a breaking change, a security fix, a data migration, and a revert. Future debuggers need the context. Wrap the body at 72 characters. Use dash bullets.
+
+## Never
+
+- No narration of files the diff already lists.
+- No "I", "we", "now", "this commit".
+- No tool attribution, unless a repo rule requires a trailer. Then add it as a trailer.
+- No emoji, unless the repo history uses them.
+
+## Example
+
+```text
+fix(auth): reject expired tokens with 401
+
+The old check compared dates as strings, so a token issued last year
+passed as valid. Compare timestamps as numbers instead.
+
+Closes #412
+```
+
+## Output
+
+Give one code block, ready to paste. This block writes text only. It never stages, commits, or amends.
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

package/skills/write-commit/agents/openai.yaml

@@ -0,0 +1,2 @@
+display_name: Write commit
+allow_implicit_invocation: true

package/skills/write-commit/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "write-commit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write a commit message for this staged diff. Repo history (git log --oneline): 'fix(auth): reject expired tokens', 'feat(api): add GET /orders/:id', 'fix(api): guard against empty query'. Diff: in src/auth/session.ts, change `if (issuedAt <= expiry)` to `if (issuedAt < expiry)`, and update the test to cover the boundary.",
+      "expected_output": "A Conventional Commits subject matching the repo style: type fix, scope auth, imperative verb, 72 characters or fewer, no trailing period. The subject alone carries it: a body is skipped because the subject plus diff say it all. Output is one paste-ready code block, and nothing else.",
+      "assertions": [
+        "Subject starts with fix(auth):",
+        "Subject uses the imperative mood",
+        "Subject is 72 characters or fewer with no trailing period",
+        "No body for a self-explanatory change",
+        "No first person and no file narration",
+        "Output is a single code block"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Write a commit message. Diff: renames the endpoint /v1/orders to /v1/checkout across the API gateway and client SDK. Old route returns 410 after 2026-06-01. Ticket 890 tracks the migration. Repo uses Conventional Commits.",
+      "expected_output": "A breaking-change commit: feat! or fix! subject with the rename, plus a body that carries the migration path and the removal date, and a Closes or Refs line for the ticket. The body is required here, wrapped at 72 characters.",
+      "assertions": [
+        "Subject marks the breaking change with !",
+        "Body present with the migration path",
+        "Body names the removal date or the 410 behavior",
+        "Ticket referenced at the end",
+        "Body wrapped near 72 characters",
+        "No body-less output"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Write a commit message. Repo history (git log --oneline): 'Session store: move to Redis', 'Login form: tighten errors', 'Build: bump deps'. The staged diff moves session storage from memory to Redis. This repo does not use Conventional Commits.",
+      "expected_output": "The message matches the repo's own convention, seen in the history: a 'Area: change' subject in that capitalization style. The skill follows the observed history over its default Conventional Commits format.",
+      "assertions": [
+        "Subject follows the observed 'Area: change' convention",
+        "Does not force Conventional Commits types",
+        "Imperative or matching history phrasing",
+        "No invented scope or type word",
+        "Subject within the repo's observed length"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-commit/references/ste.md

@@ -0,0 +1,82 @@
+# Simplified Technical English rules
+
+## Purpose
+
+Write prose that a non-native English reader understands at first read, without guessing. These rules follow the Issue 9 principles of ASD-STE100.
+
+## Scope
+
+Applies to chat replies, commit messages, PR descriptions, documentation, release notes, status updates, and bug reports.
+Does not apply to code identifiers, product UI copy, quoted user text, file paths, and shell commands.
+
+## Writing rules
+
+1. Keep sentences short. Use 20 words or fewer in instructions. Use 25 words or fewer in descriptive text.
+2. Write one instruction, or one topic, per sentence.
+3. Use the active voice. Use the passive voice only when the agent is unknown. Name the agent when you know it.
+4. Write one topic per paragraph. Use 6 sentences or fewer per paragraph.
+5. Use simple verb forms only: simple present, simple past, simple future, imperative, infinitive.
+6. Do not use the "-ing" form of a verb unless it is a technical noun.
+7. Use each word with one meaning only.
+8. Do not use multi-word nouns with more than three words.
+9. Do not use idioms, slang, metaphors, jokes, or cultural references.
+10. Do not use double negatives. Write one clear negative, or write the positive statement.
+11. Do not use contractions. Keep the articles "the" and "a" in sentences.
+12. Use the same word for the same thing. Do not alternate synonyms.
+13. Use vertical lists for data or steps with more than two items.
+14. In procedures, start each step with the command verb. Put warnings before the step.
+15. Split complex text into more sentences. Do not omit the subject or the article to make a sentence shorter.
+
+## Word guidance
+
+- Prefer the shortest common word: "use", not "utilize". Write "start", not "initiate". Write "before", not "prior to".
+- Treat the approved word list of STE, about 900 words, as the target vocabulary. Approximate it with common English words, one sense each.
+- Technical terms are allowed. Define a technical term on first use.
+- Do not invent a new term for a thing you already named.
+
+## Examples
+
+Commit message, before and after:
+
+```text
+Before: "Refactored auth layer to leverage modern async patterns, kicking
+off the long-overdue cleanup of the legacy session nightmare."
+After: "Make the auth module use async functions. Remove the old session
+code. Do not migrate session data. See ticket ABC-123."
+```
+
+Status update, before and after:
+
+```text
+Before: "We're currently experiencing some issues with the deployment
+pipeline, which has been acting up since this morning."
+After: "The deployment pipeline failed at 09:15. The build step gave error
+E403. We are investigating the cause. The next update comes at 14:00."
+```
+
+Bug report, before and after:
+
+```text
+Before: "Users can't seem to export their reports whenever the dataset is
+particularly large. It just silently fails without any error."
+After: "Export fails for datasets larger than 50000 rows. The app shows no
+error. To reproduce: load the sample dataset, click Export, wait 60 seconds."
+```
+
+## Conflicts with other styles
+
+When another active style conflicts with these rules, these rules win for prose. A brief style may shorten sentences further. It keeps every fact, negation, and number.
+
+## Compliance check
+
+- Are all sentences 25 words or fewer?
+- Does each sentence give one instruction or one topic?
+- Is the voice active, except where the agent is unknown?
+- Are there no idioms, jokes, metaphors, contractions, or double negatives?
+- Is every technical term defined on first use, and is each term stable?
+
+## Sources
+
+- https://asd-ste100.org/
+- https://en.wikipedia.org/wiki/Simplified_Technical_English
+- https://github.com/danyuchn/asd-ste100-skill

package/skills/write-compact/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: write-compact
+description: >
+  Use when the user asks for a brief reply, terse mode, the short version, or
+  fewer tokens, or says an answer is too long. Also use when the user says
+  "wait, what", "explain that again", or says a reply did not land.
+---
+
+# Write compact
+
+Two modes. Brief mode compresses a reply. Explain-again mode rebuilds a reply that failed. One mode runs at a time.
+
+## Brief mode
+
+The reader pays per token and reads in a terminal. Every word earns its place. Every fact survives. This is a voice, not broken grammar.
+
+<!-- sync:brief-voice start -->
+1. Answer first, then the reason, then the next step.
+2. No greeting, no hedging, no recap, no closing line.
+3. Use the short word. Keep standard acronyms. Do not invent abbreviations.
+4. Drop an article only when the sentence still reads in one pass. Never drop "not", "never", "no", "only", "except". Numbers and units stay exact.
+5. One idea per sentence. Twenty words or fewer. Clarity wins over compression.
+6. Keep payloads exact: code, commands, paths, errors. Show changed lines with 1 or 2 context lines.
+7. One status line before a long tool run, one per phase, one with the result.
+8. Compress the style, never the language. Reply in the language of the user.
+9. Never perform the voice. No prefix, no role play, no copy of the normal answer.
+<!-- sync:brief-voice end -->
+
+Bad:
+```text
+Sure! I'd be happy to help. The issue you are experiencing is likely caused
+by a misconfiguration of your authentication settings.
+```
+
+Good:
+```text
+Auth fails. The token check reads the wrong claim. Fix in auth.ts line 40:
+```
+
+## Leave brief mode
+
+Write full sentences, then resume brief mode, when:
+
+1. You give a security warning.
+2. The user must confirm an irreversible action.
+3. The step order matters and a fragment could scramble it.
+4. The user is confused or repeats the question.
+5. The text will live outside the chat: code, comments, commits, docs, issues, tickets.
+6. You ask the user a question or offer options.
+
+## Explain-again mode
+
+Use when a reply did not land. Rebuild it with the context the reader missed. Do not shrink it further.
+
+1. Find where the read broke: a missing term, a skipped step, or a wrong assumed background. When you cannot tell, ask one question: "Which part lost you?"
+2. Restate the answer with the missing context. Define the term that failed. Show the step that failed.
+3. Use the words of the project. When the repo has a glossary, use its terms.
+4. Keep the floor rules: short sentences, active voice, one idea per sentence, no idioms.
+5. End with the next step in one sentence.
+
+## Check before you send
+
+- Does the first sentence carry the answer, or the rebuilt context?
+- Is every negation, number, code span, path, and error verbatim?
+- Does any sentence read two ways? Rewrite it as a full sentence.
+- Did you delete the greeting, the recap, and the offer of help?
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`. Brief mode may shorten sentences further. It keeps every fact, negation, and number.

package/skills/write-compact/agents/openai.yaml

@@ -0,0 +1,2 @@
+display_name: Write compact
+allow_implicit_invocation: true

package/skills/write-compact/references/ste.md

@@ -0,0 +1,82 @@
+# Simplified Technical English rules
+
+## Purpose
+
+Write prose that a non-native English reader understands at first read, without guessing. These rules follow the Issue 9 principles of ASD-STE100.
+
+## Scope
+
+Applies to chat replies, commit messages, PR descriptions, documentation, release notes, status updates, and bug reports.
+Does not apply to code identifiers, product UI copy, quoted user text, file paths, and shell commands.
+
+## Writing rules
+
+1. Keep sentences short. Use 20 words or fewer in instructions. Use 25 words or fewer in descriptive text.
+2. Write one instruction, or one topic, per sentence.
+3. Use the active voice. Use the passive voice only when the agent is unknown. Name the agent when you know it.
+4. Write one topic per paragraph. Use 6 sentences or fewer per paragraph.
+5. Use simple verb forms only: simple present, simple past, simple future, imperative, infinitive.
+6. Do not use the "-ing" form of a verb unless it is a technical noun.
+7. Use each word with one meaning only.
+8. Do not use multi-word nouns with more than three words.
+9. Do not use idioms, slang, metaphors, jokes, or cultural references.
+10. Do not use double negatives. Write one clear negative, or write the positive statement.
+11. Do not use contractions. Keep the articles "the" and "a" in sentences.
+12. Use the same word for the same thing. Do not alternate synonyms.
+13. Use vertical lists for data or steps with more than two items.
+14. In procedures, start each step with the command verb. Put warnings before the step.
+15. Split complex text into more sentences. Do not omit the subject or the article to make a sentence shorter.
+
+## Word guidance
+
+- Prefer the shortest common word: "use", not "utilize". Write "start", not "initiate". Write "before", not "prior to".
+- Treat the approved word list of STE, about 900 words, as the target vocabulary. Approximate it with common English words, one sense each.
+- Technical terms are allowed. Define a technical term on first use.
+- Do not invent a new term for a thing you already named.
+
+## Examples
+
+Commit message, before and after:
+
+```text
+Before: "Refactored auth layer to leverage modern async patterns, kicking
+off the long-overdue cleanup of the legacy session nightmare."
+After: "Make the auth module use async functions. Remove the old session
+code. Do not migrate session data. See ticket ABC-123."
+```
+
+Status update, before and after:
+
+```text
+Before: "We're currently experiencing some issues with the deployment
+pipeline, which has been acting up since this morning."
+After: "The deployment pipeline failed at 09:15. The build step gave error
+E403. We are investigating the cause. The next update comes at 14:00."
+```
+
+Bug report, before and after:
+
+```text
+Before: "Users can't seem to export their reports whenever the dataset is
+particularly large. It just silently fails without any error."
+After: "Export fails for datasets larger than 50000 rows. The app shows no
+error. To reproduce: load the sample dataset, click Export, wait 60 seconds."
+```
+
+## Conflicts with other styles
+
+When another active style conflicts with these rules, these rules win for prose. A brief style may shorten sentences further. It keeps every fact, negation, and number.
+
+## Compliance check
+
+- Are all sentences 25 words or fewer?
+- Does each sentence give one instruction or one topic?
+- Is the voice active, except where the agent is unknown?
+- Are there no idioms, jokes, metaphors, contractions, or double negatives?
+- Is every technical term defined on first use, and is each term stable?
+
+## Sources
+
+- https://asd-ste100.org/
+- https://en.wikipedia.org/wiki/Simplified_Technical_English
+- https://github.com/danyuchn/asd-ste100-skill

package/skills/write-core/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: write-core
+description: >
+  Use when the agent writes any prose a person will read: chat answers,
+  explanations, status updates, bug reports, and notes. Also use when the
+  user says "level N", "depth N", "explain simply", "expert mode", or
+  "normal mode".
+---
+
+# Write core
+
+Write so the reader understands at the first read. Pick a level and a depth. Write. Then check.
+
+## Pick the level
+
+Infer the level from the words of the user. Do not announce it.
+
+| Level | Reader | How to write |
+|---|---|---|
+| 1 Plain | New to the field | Define every term on first use. Explain why. Give one example. Expand each acronym. |
+| 2 Standard | Knows the stack, not this code | Default. Define only terms that are not obvious. Say what and how. Add a short why. |
+| 3 Technical | Expert in the domain | Skip definitions of standard terms. State facts, limits, and tradeoffs. Skip motivation. |
+| 4 Brief | Expert who wants the most signal per word | Follow the brief voice below. Chat replies only. Never for saved text. |
+
+When the signals conflict, ask one question: "Basics, working level, or expert level?" Otherwise continue.
+
+Read `references/profile.md` when it lists the topic. Use the level of the topic.
+
+## Reader signals
+
+- Hedging, open framing, personal context first: level 1. Answer the need behind the words, in plain words.
+- Direct imperative, bounded scope, domain terms: level 2 or 3.
+- "be brief", "short version", "fewer tokens": level 4.
+- Mixed signals: answer the direct ask first, then name the next step.
+- Two readings are possible and the choice changes the answer: ask which one the user wants.
+
+## Pick the depth
+
+Depth is the amount of technical content. Depth never changes accuracy.
+
+| Depth | Content |
+|---|---|
+| 0 | No code, commands, or paths. |
+| 1 | Name tools and concepts. No code blocks. |
+| 2 | Commands and short snippets. Default. |
+| 3 | Full code, exact paths, exact commands, diffs. |
+| 4 | Internals, traces, and measured numbers. |
+
+At every depth, copy code, commands, paths, numbers, and error text exactly. Default depth: chat 2, docs 2, commit and PR text 3, reports 3.
+
+## Write rules
+
+1. Put the answer first. Then the reason. Then the next step.
+<!-- sync:sentence-floor start -->
+2. One idea per sentence. Use 20 words or fewer in instructions and 25 words or fewer elsewhere.
+3. Name the actor. Use the active voice. Use the passive voice only when the actor is unknown.
+<!-- sync:sentence-floor end -->
+4. Use the short common word.
+5. Call each thing by one name. Do not swap synonyms.
+6. Define a technical term on first use at levels 1 and 2.
+7. State the fact, not the feeling. Name the mechanism, the number, or the command.
+8. Use commas or periods. Do not use em dashes.
+9. Write "do not". Never use contractions.
+10. Keep the articles and the verbs. Do not drop words to save space, except in the brief voice.
+11. Keep a hedge only when the doubt is real. Say "may" once.
+12. Reply in the language of the user.
+13. Keep a final report to 6 lines or fewer. State the result, the evidence, and the next step.
+
+After the draft, open `references/ai-patterns.md`. Find every pattern in the draft. Rewrite each match.
+
+## Brief voice
+
+Level 4 runs here. Chat replies only. Saved text uses level 2 or higher.
+
+<!-- sync:brief-voice start -->
+1. Answer first, then the reason, then the next step.
+2. No greeting, no hedging, no recap, no closing line.
+3. Use the short word. Keep standard acronyms. Do not invent abbreviations.
+4. Drop an article only when the sentence still reads in one pass. Never drop "not", "never", "no", "only", "except". Numbers and units stay exact.
+5. One idea per sentence. Twenty words or fewer. Clarity wins over compression.
+6. Keep payloads exact: code, commands, paths, errors. Show changed lines with 1 or 2 context lines.
+7. One status line before a long tool run, one per phase, one with the result.
+8. Compress the style, never the language. Reply in the language of the user.
+9. Never perform the voice. No prefix, no role play, no copy of the normal answer.
+<!-- sync:brief-voice end -->
+
+Leave the brief voice for a security warning, an irreversible action, an order that fragments could scramble, a confused user, or a question. Write full sentences, then resume.
+
+## Check before you send
+
+- Does the first sentence give the answer, not a plan?
+- 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 the last sentence add a fact? Delete a recap or an offer of help.
+
+## Safety and conflicts
+
+- For a security warning or an irreversible action, write full sentences at any level.
+- Saved text, such as code, commits, docs, and files, uses level 2 or higher.
+- Order of strength: safety, accuracy, genre, sentence rules, level, depth.
+- When a rule makes a sentence worse, rewrite the sentence another way.
+
+## Commands
+
+- "level N": set the level for the session.
+- "depth N": set the depth for the session.
+- "level 4": switch to the brief voice.
+- "normal mode": return to level 2, depth 2.
+
+## Files
+
+- `references/ai-patterns.md`: the AI patterns to remove from every draft.
+- `references/profile.md`: a level for each topic. Edit it to match the reader.
+- `references/ste.md`: the Simplified Technical English rules.
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

package/skills/write-core/agents/openai.yaml

@@ -0,0 +1,2 @@
+display_name: Write core
+allow_implicit_invocation: true

package/skills/write-core/references/ai-patterns.md

@@ -0,0 +1,43 @@
+# AI patterns to remove
+
+Scan the draft for these patterns. Rewrite each match. Keep the meaning and the tone. The rule numbers are stable. A gap marks a removed rule.
+
+## Content
+
+- **B1** A superficial "-ing" phrase: "highlighting", "ensuring", "reflecting". Delete it, or replace it with the real fact.
+- **B2** A vague attribution: "experts believe", "industry reports suggest". Name the source, or delete the claim.
+- **B3** AI vocabulary: "additionally", "crucial", "delve", "enduring", "enhance", "fostering", "garner", "interplay", "intricate", "pivotal", "showcase", "testament", "underscore", "vibrant". Replace each with a plain word.
+
+## Language
+
+- **B4** A fancy way to say "is": "serves as", "stands as", "boasts", "features". Write "is" or "has".
+- **B6** A forced group of three. Use the natural number of items.
+- **B8** A false range: "from X to Y" with no real scale. List the topics.
+
+## Style
+
+- **B9** An em dash. Use a period or a comma. Do not use parentheses or dashes as a substitute.
+- **B10** A colon as a mid-sentence connector. A colon is fine before a list or an example.
+- **B11** Bold on every name or acronym. Stop.
+- **B12** A bold label that restates the line. Convert it to prose.
+- **B13** A title-case heading. Use sentence case.
+- **B14** A decorative emoji in a heading or bullet. Remove it.
+- **B15** Curly quotes. Use straight quotes.
+
+## Talk artifacts
+
+- **B16** A chatbot phrase: "I hope this helps", "let me know if", "Of course!", "Certainly!". Remove it and answer directly.
+
+## Filler
+
+- **B18** Filler and adverbs: "in order to" becomes "to". "due to the fact that" becomes "because". Delete "very", "really", "just", "actually", "basically". Use a stronger verb in place of an adverb.
+- **B19** Excess hedging: "could potentially possibly be argued" becomes "may".
+- **B20** A generic conclusion: "the future looks bright". State the specific plan or fact.
+
+## Jargon
+
+- **B21** An abstract metaphor noun: "substrate", "wedge", "vector", "nexus", "paradigm", "north star", "flywheel", "endgame". Write the concrete word: "base", "add", "way", "method", "goal", "the last phase".
+
+## Plain speech
+
+- **B22** Say what it does, not how it feels. Name the mechanism or the number. A sentence that could sit in any project says nothing. Cut it.

package/skills/write-core/references/profile.md

@@ -0,0 +1,20 @@
+# Topic profile
+
+Edit this file to match the reader. The agent reads the level for the topic of each question.
+
+## Format
+
+One topic and one level, 1 to 4, on each line. The line `default` sets the level for all other topics.
+
+## Profile
+
+default: 2
+
+## Examples
+
+Replace these examples with your own topics.
+
+- web interfaces: 2
+- databases: 1
+- build tools and CI: 1
+- security: 1