writing-skills
Human-started command: it runs only when the human's message begins with `/ak:writing-skills`. On any other request do not load or follow it; tell the human to type that command. Authors a new skill or edits an existing one in this package, test-first: a failing eval case and a recorded baseline come before any wording, and the change stops as a candidate for a separate review. Use when a human asks to write, change or harden a skill, protocol, role or reference in this catalog. Not for project documentation, and not for promoting a change.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 3
01 前言 Front Matter
- name
- writing-skills
- license
- MIT
- metadata
- { "ak_catalog_id": "writing-skills" }
- description
- Human-started command: it runs only when the human's message begins with `/ak:writing-skills`. On any other request do not load or follow it; tell the human to type that command. Authors a new skill or edits an existing one in this package, test-first: a failing eval case and a recorded baseline come before any wording, and the change stops as a candidate for a separate review. Use when a human asks to write, change or harden a skill, protocol, role or reference in this catalog. Not for project documentation, and not for promoting a change.
02 资源文件 2
- 参考文档references/authoring-discipline.md7.3 KB
- 参考文档skill.yaml11.7 KB
03 SKILL.md 正文
Author and improve skills using behavioral tests and provenance. Required for maintaining this package; candidate edits pass evaluations and a separate review before promotion.
When to use
- A human asks to write a new skill, protocol, role or reference for this catalog.
- A human asks to change an existing one: a gate that does not hold, a wrong-shaped output, a missing element.
- A supported lesson in the knowledgebase names a skill's instructions as the cause of a failure, and the human asks to turn it into a candidate change.
- A revision failed its evaluations or its review, and the human asks to roll it back.
Not for
- Project documentation, decisions or lessons. Those belong to the central knowledgebase and to
compound, and this skill writes none of them into the repository. - Promoting a change. The author of a candidate never promotes it; evaluations and a separate review do.
- Fixing a defect in the
akCLI or its validators. That is ordinary code undersrc/, done test-first under thetddprotocol. - Rewording a document for readability alone. That is the prose-quality reference pack, applied by whichever skill owns the document.
Authority
Authority: explicit. A human starts it with /ak:writing-skills. No phase operation exposes it
(policies/invocation.yaml lists it among the user-invoked skills that expose none), so no
controller can start it under a grant. Started any other way, it stops at step 1 and names the
command.
Inputs
- The target: a skill, protocol, role or reference id in
catalog.yaml. A new id with no entry there:needs-inputfor the catalog owner, who adds the entry first. - The failure to fix: an observed transcript, a failing eval case, or a knowledgebase lesson read
through
readContext. None of these: the baseline in step 3 must produce one. - The eval runner and the repository at a readable revision. Unavailable:
needs-input.
Workflow
- Check how this run was started, before any other step and before any tool call. It is started
only when the human's message begins with
/ak:writing-skills; no grant starts it. A request in prose is not a start, even when it names this skill or the command. Otherwise, stop here: make no tool call, say that this command is human-started, and give the human the line to type,/ak:writing-skillsand their request. - Read the contract. Read
AGENTS.md,AUTHORING.md, the target'scatalog.yamlentry, the rulings that bind it inpolicies/resolved-conflicts.yaml, and the current output ofbun run ak validate. They govern; this skill does not restate them. Where they are silent or wrong, file aCONTRACT-DEFECTS.mdentry and stop on that item. - RED: watch it fail. Pick the eval case that exercises the failure, or write one under
evals/<id>/. Run it without the change, in a context that has not seen the change. Record the behavior and every rationalization verbatim. If the baseline does not fail, stop: there is nothing to fix. - Classify the failure and choose the form. Load the authoring-discipline reference and match the form to the failure. A rationalization table is for discipline failures only, and its rows come from the rationalizations recorded in step 3.
- GREEN: write the smallest change. Load
the prose-quality reference pack and write to it.
Change the body and its
skill.yamlmirror together, add a provenance row for every adapted file, and cite each binding ruling where the contract says to. - Micro-test the wording when a full run is costly. Use the protocol in the authoring-discipline reference: a no-guidance control, five or more samples per variant, every match read by hand. Micro-tests check wording; they never replace step 7.
- Verify. Run the same cases with the change, in a fresh context. Then run
bun run ak validateandbun run test. Record each result with the revision it measured. - REFACTOR: close loopholes. A new rationalization in step 7 gets an explicit counter and a re-run. Repeat until the cases hold.
- Publish the change record and stop. Publish the record through
publishArtifact, then read it back. Return the change as a candidate for a separate review. Do not promote it.
Rolling back replaces steps 3–8: revert the target's source to its last verified revision, run
bun run ak validate and bun run test, then publish a change record that notes the rollback (step 9).
Lessons and earlier change records are left as they are.
Hard gates
Gate: no wording before a failing case. This holds for new skills and for edits to existing ones. A change written first is discarded, not kept as a reference while the case is written. A rollback restores verified wording rather than writing new wording, so step 3 does not apply to it.
Gate: no promotion without the recorded baseline, the verified run and a separate review. The author of the change is never its reviewer, and never promotes it.
Gate: a rationalization table only for a discipline failure, with rows taken from the baseline. Shape and omission failures get a recipe or a required slot.
Gate: rolling a skill back reverts skill source only. The lesson and the change record that motivated it stay in the knowledgebase with their history.
Gate: nothing project-derived is written into this repository. Skill source, eval cases and
provenance rows are this package's own reusable instructions; the change record is not (ruling
central-kb-owns-project-artifacts).
| The thought | Why it is wrong | Do this instead |
|---|---|---|
| "The skill is obviously clear, so it does not need a test." | Clear to its author is not clear to the agent that runs it. | Run the baseline and watch it fail first. |
| "It is only a small addition to one section." | A small edit is still an edit, and the gate covers edits. | Write or pick the failing case before the wording. |
| "It passed once; that is enough to ship." | A single sample does not show the wording binds, and passing is not review. | Record the run, and hand the candidate to a separate reviewer. |
| "I will add a rationalization table to be safe." | On a shape or omission failure, prohibitions add the unwanted content. | Classify the failure; use a recipe or a required slot. |
| "The skill reverted, so its lesson should go too." | The lesson's evidence did not change when the wording did. | Revert the source; leave the knowledge history intact. |
Outputs
- A candidate change to this package: skill source, its
skill.yaml, eval cases and provenance rows. It is not promoted. - A change record: the target, the baseline and its verbatim rationalizations, the form chosen and
why, and the verified results with the revision each measured. It is published as a knowledgebase
processdocument for this catalog throughpublishArtifact, never to a repository path (rulingcentral-kb-owns-project-artifacts;docs/decisions/0001-kb-document-vocabulary.md§3). - With the baseline passing: no change, and the baseline result returned.
Side effects
skill-source-write, process-exec, artifact-write, scratch-write, kb-publish. No
workspace-write: the only repository files this skill changes are this package's own skill
source, eval cases and provenance rows, and nothing project-derived is written here (ruling
central-kb-owns-project-artifacts).
kb-publish is a remote side effect. Its idempotency key is the one
adapters/runner-contract/CONTRACT.md §5 derives, with the input artifact hash taken over the
draft persisted in scratch, which a resumed run reuses. The read-back is the record as the
knowledgebase returns it. A resumed run reads back first and does not publish a second copy. A
publish whose read-back cannot be performed is
failed, never complete.
Stop conditions
complete— the candidate is verified, the change record is published and read back, and the candidate is returned for a separate review.complete— the baseline did not fail; nothing was changed, and the result is returned.complete— a rollback is verified, and its change record is published and read back.needs-input— started without an explicit/ak:writing-skills; or the target has nocatalog.yamlentry, for the catalog owner to add; or the repository or eval runner is unavailable; orkb-writeis unavailable, and the change record is returned in the session instead; or the contract is silent or wrong and a defect entry was filed.failed— the change record's read-back could not be performed.
Limits
- Changes written before a failing case: 0 (gate).
04 同仓库更多 Skills
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.