write-skills 0.0.0-stage → 0.2.0

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

package/skills/write-core/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-docs/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: write-docs
+description: >
+  Use when the agent writes or revises a technical document: README,
+  tutorial, how-to guide, reference page, explanation, RFC, design note, or
+  release note. Also use for a document an agent reads, such as a skill file
+  or an agent instruction file.
+---
+
+# Write docs
+
+A tired engineer understands the document at the first read. Settle the job of the document, then hold every sentence to the rules. For the full standard, open `references/docs-standard.md`.
+
+## Settle the job first
+
+One document, one job. Two facts pick it: does the reader act or understand, and are they learning or working?
+
+| Job | What the reader leaves with |
+|---|---|
+| Tutorial | A working thing they built with you, step by step. |
+| How-to | A solved problem, through steps alone. |
+| Reference | The fact they came to look up. |
+| Explanation | The reason the thing is the way it is. |
+
+Jobs stay separate. Split the page and link, rather than mixing.
+
+## Sentence rules
+
+1. Cut every word that does no work.
+<!-- 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. Prefer the short everyday word, unless the long one buys precision.
+5. Write to the reader as "you", in the now.
+6. Steps are commands, and the gate comes before the action it guards.
+7. The normal path comes first. The exceptions wait below it.
+8. Pin "only" and "not" next to the word they change.
+9. Unstack the nouns, and give every "it" and "this" exactly one target.
+10. A period beats a semicolon. A new sentence replaces a dash. No slash-joins, no "(s)" plurals.
+11. One thing carries one name across the whole document.
+12. Name the real symbols, paths, flags, and commands. The codebase supplies the words.
+
+## Revise an existing document
+
+1. Read the whole page once before you change a line.
+2. Settle the job of the page. Check every section against that job.
+3. Repair the sentences that break the rules. Leave the sentences that hold.
+4. Do not reword text that did not change. A rewrite of untouched text costs the reviewer time.
+
+## Rhythm
+
+A page can pass every rule and still read like a machine wrote it.
+
+- Vary the sentence length on purpose. A short sentence lands a point.
+- Take a position where the job allows it. Explanation weighs options. Reference stays neutral.
+- Trade the sterile for the particular. "A column rename fails the build" beats "schema changes can cause issues".
+
+## Agent mode
+
+When an agent reads the document, add the scan rules. Skill files and agent instruction files follow this mode.
+
+- Give every section a stable heading. The agent navigates by headings.
+- End every step on a condition that tells the agent the step is done. Make the condition checkable.
+- State what the environment does not show: the reason for a choice, the trap, the convention.
+- Keep one meaning in one place. Do not restate a rule in a second section.
+- Prune stale lines on every edit. A wrong instruction costs more than a missing one.
+
+For the full agent-doc standard, open `references/agent-docs.md`.
+
+## Worked example
+
+Before:
+```text
+The configuration of retry behavior for the mail client is handled in
+client.json. Running the client with --dry-run will output what would
+have been sent, which is useful to know. If settings are wrong, errors
+may occur.
+```
+
+After:
+```text
+`mail.ts` reads the retry count and the delay from `client.json`. Each
+retry waits twice as long as the one before it. Run `mail.ts --dry-run`
+to print the messages without sending them.
+```
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

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

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

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

@@ -0,0 +1,42 @@
+{
+  "skill_name": "write-docs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Revise this README paragraph: 'Configuration of the exporter is performed via exporter.json. Note that it's important to remember that running with --reset should only be done when you want to forget all state, as data loss may occur if misused.'",
+      "expected_output": "The revision names the real actor and file, puts the condition before the action, cuts the filler, and keeps every fact. Untouched meaning stays in place.",
+      "assertions": [
+        "Real symbol and flag names kept",
+        "Warning placed before the action",
+        "Filler deleted: 'note that', 'it's important to remember'",
+        "Active voice, actor named",
+        "No facts lost"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Plan a short doc page that teaches a newcomer to run their first import with our CLI tool. Choose the document job and outline the page.",
+      "expected_output": "Tutorial job chosen: build-a-thing framing, every step shows a visible result, written as commands. No reference tables or argument sections mixed in.",
+      "assertions": [
+        "Chooses tutorial and says why",
+        "Opens with what the learner ends with",
+        "Steps produce visible results",
+        "No mixed modes"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Write the structure for an agent instruction file that a coding agent reads on every run: how to run tests, what never to commit, and where the domain glossary lives.",
+      "expected_output": "Agent mode: stable headings, steps with checkable end conditions, facts the environment does not show, one meaning in one place.",
+      "assertions": [
+        "Stable headings per topic",
+        "Steps end on checkable conditions",
+        "Points at the glossary location",
+        "No restated rules"
+      ],
+      "files": []
+    }
+  ]
+}

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

@@ -0,0 +1,77 @@
+# Agent-doc standard
+
+For documents an agent reads: skill files, agent instruction files such as AGENTS.md, and memory files. The goal is a predictable process: the agent takes the same path on every run. The same levers work for all three shapes.
+
+## Context pointers
+
+A context pointer names material that sits outside the context, and states when to reach it. A skill description is one. A line in an instruction file that names a doc is the same object.
+
+- The wording of the pointer, not its target, decides when the agent reaches the material, and how reliably.
+- A pointer does two jobs: state what the material is, and list the cases that should trigger it.
+- Put the key word first. The start of the pointer does the trigger work.
+- One trigger per case. Synonyms that rename one case are one case written twice. Cut them.
+- A weak pointer in front of a must-have target is a bug. Sharpen the wording first. Inline the material only when sharpening fails.
+
+## The two loads
+
+Every document and pointer spends one of two budgets.
+
+- Context load is the cost of always-present material: an instruction file line, a skill description. It spends attention on every turn, fired or not.
+- Cognitive load is the cost on the human: which documents exist, and when to reach for each. The human is the index.
+- Spend cognitive load where human judgment matters. Remove it where it does not.
+
+## Information hierarchy
+
+A document holds steps, the ordered actions, and reference, the facts read on demand. Each piece sits on a ladder ranked by how soon the agent needs it.
+
+1. In-file step: what the agent does, in order. The primary tier.
+2. In-file reference: rules and facts read on demand. A flat set of peer rules is a fine shape.
+3. Disclosed reference: a separate file behind a pointer, loaded only when the pointer fires.
+
+Push too little down and the top bloats. Push too much down and you hide material the agent needs.
+
+- Move material down the ladder so the top stays legible. This protects the hierarchy, not only the token count.
+- The cleanest test: inline what every path needs. Push behind a pointer what only some paths reach.
+- Keep the definition, the rules, and the caveats of one concept under one heading. Reading one part then carries its neighbors.
+- A document can be too long even when every line is live. The cure is the ladder, not deletion of meaning.
+
+## Completion criteria
+
+Every step ends on a condition that tells the agent the step is done.
+
+- Make the condition checkable: can the agent tell done from not done?
+- Make the condition demanding: "account for every changed model" forces thorough work. "List the changes" does not.
+- A vague bound invites an early stop. Sharpen the bound first. Only a bound that cannot be made sharp justifies hiding the later steps behind a split.
+- A demanding criterion also binds flat reference: "apply every rule" holds a rule set to full coverage.
+
+## Leading words
+
+A leading word is a compact concept the model already knows. Used as a repeated token, it anchors a region of behavior in few words.
+
+- Reach for a word that already exists in pretraining. A made-up word recruits nothing and pays in definition.
+- The same word in your prompts, your docs, and your code links them all to the material, and the agent reaches it more reliably.
+- One strong word replaces a spelled-out triad. "Fast, deterministic, low overhead" collapses into one word the reader already holds.
+
+## State the positive
+
+Steering by prohibition names the behavior you do not want and makes it more available, not less.
+
+- State the target behavior, so the banned one is never spoken.
+- Keep a prohibition only as a hard guardrail you cannot phrase in positive form. Pair it with the positive target.
+- A weak instruction the model already obeys by default says nothing. Delete it. When it fails the default test, the fix is a stronger word, not more words.
+
+## Pruning
+
+- Keep each meaning in one authoritative place, so a change is a one-place edit. The same meaning in two places costs maintenance and tokens.
+- The environment is a source of truth too: config files, scripts, directory layout, help output. Do not restate what the agent can look up. It goes stale.
+- Cache only what the environment cannot show: the reason behind a choice, the trap, the convention nobody wrote down.
+- Check every line for relevance on every edit. Stale layers settle because adding feels safe and removing feels risky. Core down through them.
+- Delete a sentence that fails the default test whole. Do not trim words from it.
+
+## Skill files
+
+When the document is a skill file, add:
+
+- Frontmatter holds the name and the description. The description states when to use the skill. It never summarizes the workflow.
+- Keep the skill auto-invoked when the agent must reach it on its own. Restrict it to manual use only when the human is the sole caller.
+- When manual skills multiply past memory, one router names them all, and when to reach for each.

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

@@ -0,0 +1,103 @@
+# Docs standard
+
+The standard behind the document writer, as four questions. Ask them in order, when you draft and when you review.
+
+## What job does this document do?
+
+A document does one job. Settle the job before the first sentence. Two facts pick the job. Does the reader try to get something done, or to understand? Are they learning the field, or already working in it?
+
+| Job | What the reader leaves with |
+|---|---|
+| Tutorial | A working thing they built with you, step by step. |
+| How-to | A solved problem, through steps alone. |
+| Reference | The fact they came to look up. |
+| Explanation | The reason the thing is the way it is. |
+
+**Tutorial.** You carry the newcomer. Their finished result is your responsibility, not theirs. Start with the thing they will have at the end. Every step ends in something they can see: output, a changed prompt, a log line. Park the theory in one clause and a link. Teach in the first person plural, as commands.
+
+**How-to.** The reader already works in the field. Give the path to one goal and hold the teaching. Steps, decisions at forks, and links for the background. Name the page after the task the reader came for.
+
+**Reference.** The reader is mid-task and wants a fact. Give facts, options, limits, and failure modes, with no opinion and no persuasion. Shape the page like the thing it describes, so both can be walked in the same order. Where code can generate the page, generate it.
+
+**Explanation.** One bounded subject that still reads outside the product. Open on a real question about why. Bring in the decisions, the history, the constraints, and the roads not taken. This is the one job where the writer may argue a position.
+
+Keep the jobs apart. A reference table inside a tutorial stalls the lesson; a how-to that argues slows the fix. Split the page and link.
+
+## Do the sentences talk to the reader?
+
+- Write to "you", in the now. Reserve "will" for events that truly sit in the future.
+- Give every action an owner: "the loader parses the file". The passive voice earns its place only when the doer is unknown or beside the point.
+- Steps are commands: "Click Submit." A step never "should be done"; it is done.
+- Put the gate before the action it guards, so a reader who does not qualify can jump past.
+- The normal path comes first. The exceptions wait below it.
+- Write like a colleague who knows the subject. Instructions skip "please". Procedures never claim to be "simple", "easy", or "quick"; a reader in a procedure is stuck, or they would not be there.
+- Promise nothing ahead of time, and do not open two sentences in a row with the same words.
+- A link says where it goes, in its own words. A bare "click here" says nothing.
+- Headings state the point, in sentence case. A task heading is a verb phrase; a concept heading is a noun phrase. One h1, no level skips.
+- Sequences take numbers. Everything else takes dashes. A list gets a lead-in sentence and parallel items.
+- Code sits in code font, screen parts in bold, series get their final comma. When a list is partial, say so up front instead of ending with "etc.".
+
+## Does each sentence carry one thing?
+
+- One instruction, or one thought, per sentence. Long sentences split: near 20 words for instructions, near 25 elsewhere.
+- Warnings arrive before the step they protect.
+- Articles stay. "Remove backup file" asks a question; "Remove the backup file" answers it.
+- A word keeps one meaning and one role for the whole document.
+- One verb per action, kept for the whole document.
+- Procedures are commands, never stories and never passive.
+- The "-ing" form of a verb takes on too many roles. Prefer the plain form.
+
+## Can any sentence be read two ways?
+
+- "Only" and "not" stand next to the word they change. "Only fails on growth" and "fails only on growth" disagree.
+- Unstack the nouns. "The proto import budget check script" becomes "the script that checks the proto-import budget".
+- Every "it", "they", and "this" points at exactly one thing. In doubt, say the noun again.
+- Half-written pairs mislead. "Phase 1 moves the converters and Phase 2 the runtime" starves Phase 2 of its verb. Give it one.
+- Small joining words stay when they settle the parse: "Ensure that the switch is off".
+- Two articles prevent a false pair: "the client and the host" when they are two things.
+- Say what "and" and "or" join: "both, and", "either, or", "if, then".
+- A period beats a semicolon. A new sentence replaces a dash.
+- Parentheses hold a whole grammatical unit, or nothing. Plurals never come from "(s)".
+- Write "a, b, or both" over "a/b".
+- One thing carries one name across the whole document. Three names for one thing force three memories.
+- Idioms, slang, and Latin shortforms leave. A reader working in a second language, a translator, and an agent all parse plain constructions fastest.
+
+## Three rules above all
+
+1. When the sentence survives without a word, the word goes.
+2. The short everyday word wins, unless the long one buys precision.
+3. A rule that makes the sentence worse loses. Fix the sentence another way, or leave it.
+
+The codebase supplies the words. Name the real symbol, file, flag, and command. Jargon you invent gets replaced by what a developer would say out loud.
+
+## Keep it human
+
+A page can pass every rule and still read like a machine wrote it. Every sentence the same length. No position taken. Nothing particular in sight.
+
+- Vary the length on purpose. A short sentence lands a point. A long one carries a fact together with its condition or its cost.
+- 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.
+
+## Claims and evidence
+
+- Write the symbols and paths that exist at this commit.
+- A count or a tree in the page stays true at the commit that carries it, and the page includes the command that regenerates it.
+- PR bodies and commit messages are documents too, with every rule here except the job rule. A PR body is a one-minute briefing.
+- Product UI text is not a document. The product copy rules own it.
+
+## Worked example
+
+Before:
+```text
+The configuration of retry behavior for the mail client is handled in
+client.json. Running the client with --dry-run will output what would
+have been sent, which is useful to know. If settings are wrong, errors
+may occur.
+```
+
+After:
+```text
+`mail.ts` reads the retry count and the delay from `client.json`. Each
+retry waits twice as long as the one before it. Run `mail.ts --dry-run`
+to print the messages without sending them.
+```

package/skills/write-docs/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-jira/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: write-jira
+description: >
+  Use when the user asks for Jira epics, stories, tickets, or story points,
+  or asks to break a plan, spec, or discussion into ticket text.
+---
+
+# Write Jira tickets
+
+Turn a plan into tickets an engineer can pick up without a meeting. Each story cuts through all layers and works on its own. Slice vertical, never by layer.
+
+## Read first
+
+1. Read the plan, the spec, or the discussion the user names.
+2. Read the code area when access exists. Use the domain words of the codebase.
+3. List the slices before you write the tickets. Confirm the list with the user.
+
+## When the plan is thin
+
+A plan without a goal, a number, or a constraint is not a plan yet. Do not slice it.
+
+1. Name what is missing: the user-visible goal, the current numbers, the constraints.
+2. Ask for those facts before you draft. A story with invented targets tests nothing.
+3. When the user wants a draft anyway, mark every invented target as an assumption. Carry every unknown into the points reason.
+
+## Slice rules
+
+1. One story is one complete path through the stack: data, API, interface, tests.
+2. A finished story demos on its own. A layer without a user-visible result is not a story.
+3. Size a story to fit one work session. Split anything larger.
+4. Name the blocking stories of each story. A story with no blockers can start.
+5. A mechanical change that touches the whole repo gets its own sequence. Add the new form beside the old. Move the callers in batches. Then delete the old form.
+
+## Epic template
+
+```markdown
+Title: <outcome, not a feature word>
+
+Outcome:
+<the user-visible state when this epic closes>
+
+Scope:
+- <story list, one line each>
+
+Out of scope:
+- <what this epic does not do>
+```
+
+## Story template
+
+```markdown
+Title: <what works when this story closes>
+
+Story:
+As a <role>, I <action>, so that <value>.
+
+Acceptance criteria:
+- [ ] <a testable condition>
+- [ ] <a testable condition>
+
+Blocked by:
+- <ticket key or title, or "none">
+
+Points: <n>
+Points reason: <size, risk, or unknowns, in one line>
+```
+
+## Story points
+
+1. Estimate from three inputs: size, risk, and unknowns.
+2. Every estimate carries one reason line. A bare number carries no information.
+3. When estimates differ by much, the story hides an unknown. Split it, or list the unknown in the story.
+4. Points measure effort, not value. The value lives in the story line.
+
+## Rules
+
+- Write criteria a test can check. "The query answers in 200 ms at 10000 rows" is a criterion. "Works fast" is not.
+- Keep file paths and code out of tickets. They go stale. A schema or type shape that holds a decision can go in, trimmed to the decision.
+- This block writes text only. It never creates, edits, or moves an item in Jira.
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

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

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

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

@@ -0,0 +1,44 @@
+{
+  "skill_name": "write-jira",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Break this plan into a Jira epic with stories and story points. Plan: users want to attach files to tasks. The backend needs an attachment table and upload endpoint, the web app needs an attach button and preview, and the mobile app needs the same. Each surface should ship on its own.",
+      "expected_output": "One epic named for the outcome, plus stories that each cut a complete vertical path: data, endpoint, one client surface, tests. Each story has a testable acceptance checklist, a blocked-by line, and story points with a one-line reason built from size, risk, and unknowns.",
+      "assertions": [
+        "Epic title states the outcome, not a feature word",
+        "Each story is a vertical slice, not a layer",
+        "Acceptance criteria are testable checkboxes",
+        "Blocked-by lines present",
+        "Every points value carries a reason line",
+        "No bare points number"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Break this into Jira stories. Plan: rename the column users.email to users.login across the whole codebase. The rename touches every service that reads the column, and no vertical slice can land green on its own.",
+      "expected_output": "A sequenced chain instead of vertical slices: add the new column beside the old, migrate readers in batches, then delete the old column. Each story names the stories that block it, and the delete story is blocked by every migration batch.",
+      "assertions": [
+        "First story adds the new form beside the old",
+        "Middle stories migrate callers in batches",
+        "Final story deletes the old form",
+        "Blocking edges form a correct chain",
+        "No forced vertical slice"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Break this into Jira stories. Plan: make the dashboard faster. That is all the input you get.",
+      "expected_output": "The skill does not invent a breakdown from nothing. It asks for the missing facts, or lists the unknowns explicitly, before or instead of producing stories. Any stories it does draft carry the unknowns in the story text, and points come with a reason that names the unknowns.",
+      "assertions": [
+        "Asks for missing context or lists the unknowns",
+        "Does not fabricate measurements or causes",
+        "Stories, if drafted, carry the unknowns",
+        "Points reasons mention the unknowns"
+      ],
+      "files": []
+    }
+  ]
+}