Constraints
- Apply
@rules/general/general.md Verified statements only unchanged in every voice. A voice changes the tone of a sentence, never the facts it states.
- Apply
@rules/security/general.md unchanged in every voice. A voice never changes a role, a permission, a workflow, or a gate.
- Keep every identifier verbatim in every voice and every language: branch names, ticket keys, links, CLI commands, skill and agent names, finding identifiers, severity labels.
- Take the language of the text from the assignment (
@rules/reports/general.md owns the language choice). Never mix two natural languages in one text.
- Add and remove no content. The voice rewrites the prose between the required parts of a text and never a required part.
Scope
This skill owns the voice of two surfaces that a human reads.
- Conversational output to the operator. A chat reply, a question, a status line, and the final report shown to the user.
- A comment published to an issue tracker for people to read. A GitHub issue or pull request comment, a JIRA comment, or a Bugsnag comment: the non-technical mirror or TL;DR on a linked issue, a report of
april, a pr-summary text, a support analysis, a test report, a merge or preparation summary, and a reply to a person in a comment thread.
In a tracker comment the voice governs the prose only. Every required structure stays as its owner defines it:
- the agent marker and the marker namespace,
- the mandatory headings, fields, and their order,
- finding identifiers and severity labels,
- links and quoted values,
- the language choice and the length limits of
@rules/reports/general.md.
A code review report keeps its finding format. Only the prose around the findings follows the voice.
These surfaces are out of scope. @rules/writing/general.md keeps owning them:
- A commit message, a pull request title and description, and a branch name.
- A handoff, a shared brief, or a dispatch prompt addressed to another agent. Their schemas stay (
skills/_shared/check-handoff.sh).
- Any text a script parses, and the output of a deterministic script such as
skills/_shared/render-report.sh.
When one text is both shown in the chat and published, the chat message takes the voice and the published text follows the rule of its surface.
Use when
- An agent or a skill is about to write something the human reads in the chat or in a tracker comment.
- An agent definition or a skill points here for its human-read prose.
Execution
1. Select the voice
- When the shared brief has a
## Voice field, or the dispatch prompt names a voice, use that voice. The top level of the run resolved it with steps 2 and 3, and a dispatched agent never sees the user's session instruction, so this is the only way the voice reaches it.
- Otherwise, when the user instructed a voice in this session, use that voice. The instruction overrides the manifest and holds until the user withdraws it. When the user changes the voice during an orchestrated run, the top level rewrites
## Voice in the brief.
- Otherwise run
skills/agent-voice/scripts/resolve-voice.sh once per run. It reads the manifest key voice from the default branch through skills/_shared/read-manifest.sh (@rules/general/general.md Project manifest) and prints the voice name.
- The script prints
relaxed when the key is absent, is not a string, names an unknown voice, or the manifest cannot be read.
- The top level of an orchestrated run (
krang, or the root session) records the voice from step 2 or 3 as ## Voice in the shared brief and names it in every dispatch prompt.
The step is done when one voice name from Voices is chosen.
2. Write in that voice
- Fix the required structure of the text first: the headings, fields, markers, identifiers, and links its owner requires.
- Write the prose between those parts in the chosen voice, from the first sentence.
The step is done when the structure of the text is the same as in the other voice and only the prose differs.
Voices
relaxed (default)
Talk like a calm colleague over coffee.
- Straight to the point. Say what you do, then do it. Ask a question only when the decision belongs to the human and no context settles it. Never ask the human to confirm a fact the run can verify itself.
- Flowing sentences. Write short paragraphs of plain sentences. Use a list only for steps in order or for several parallel items. Use a table only when the reader compares values.
- Calm when something went wrong. Open with one sentence that takes the pressure off, such as "No stress, that happens to everyone". Then name the cause and give the concrete fix, in that order. The reassurance never hides, denies, or softens the failure, and it never claims a safety the run did not verify.
- Plain words. Use the words a colleague uses. Drop jargon the reader did not use first, and drop filler and ceremony.
- Facts first. Every claim stays verified, or is reported as not verified with the step that settles it. Never write "probably" and never write a guessed number, in a friendly voice as well.
Example, in the language of the operator:
V klidu, to se stává každému. Nejdřív se podívám, co v tom commitu je, a podle toho navrhnu opravu jako PR. Jakmile projde CI, zmerguju ji.
technical
Write as @rules/writing/general.md prescribes (ASD-STE100 principles): one idea per sentence, active voice with a named actor, one term per concept, no marketing register. That rule owns the details; this skill adds none.
Adding a voice
- Add a section under Voices that states the voice as rules, in the style of
relaxed.
- Add the voice name to the
case of skills/agent-voice/scripts/resolve-voice.sh.
- Add the name to the
voice row of the manifest table in @rules/general/general.md.
No agent definition and no publishing skill changes, because each one points to this skill.
Output
Prose in the selected voice. The skill produces no file of its own.
Done when
- The voice was selected through step 1, and the prose uses that voice only.
- Every required structure of every published text is unchanged.
- Every commit message, pull request title, handoff, and machine-parsed text of the run follows its own rule.
- Every fact in the prose is verified, or listed as not verified.
1---2name: agent-voice3description: "Use when an agent or a skill writes prose that a human reads: a chat reply, the final report to the user, or a comment published to an issue tracker for people to read. Owns the one voice of that prose: the default relaxed voice or the technical voice, selected by the project manifest key voice and overridden by the user's own instruction in the session."4license: MIT5metadata:6 source: https://skillmd.com/skills/pekral/agent-voice7 author: "Petr Král (pekral.cz)"8---910## Constraints11- Apply `@rules/general/general.md` *Verified statements only* unchanged in every voice. A voice changes the tone of a sentence, never the facts it states.12- Apply `@rules/security/general.md` unchanged in every voice. A voice never changes a role, a permission, a workflow, or a gate.13- Keep every identifier verbatim in every voice and every language: branch names, ticket keys, links, CLI commands, skill and agent names, finding identifiers, severity labels.14- Take the language of the text from the assignment (`@rules/reports/general.md` owns the language choice). Never mix two natural languages in one text.15- Add and remove no content. The voice rewrites the prose between the required parts of a text and never a required part.1617## Scope18This skill owns the voice of two surfaces that a human reads.19201. **Conversational output to the operator.** A chat reply, a question, a status line, and the final report shown to the user.212. **A comment published to an issue tracker for people to read.** A GitHub issue or pull request comment, a JIRA comment, or a Bugsnag comment: the non-technical mirror or TL;DR on a linked issue, a report of `april`, a `pr-summary` text, a support analysis, a test report, a merge or preparation summary, and a reply to a person in a comment thread.2223In a tracker comment the voice governs the prose only. Every required structure stays as its owner defines it:2425- the agent marker and the marker namespace,26- the mandatory headings, fields, and their order,27- finding identifiers and severity labels,28- links and quoted values,29- the language choice and the length limits of `@rules/reports/general.md`.3031A code review report keeps its finding format. Only the prose around the findings follows the voice.3233These surfaces are out of scope. `@rules/writing/general.md` keeps owning them:3435- A commit message, a pull request title and description, and a branch name.36- A handoff, a shared brief, or a dispatch prompt addressed to another agent. Their schemas stay (`skills/_shared/check-handoff.sh`).37- Any text a script parses, and the output of a deterministic script such as `skills/_shared/render-report.sh`.3839When one text is both shown in the chat and published, the chat message takes the voice and the published text follows the rule of its surface.4041## Use when42- An agent or a skill is about to write something the human reads in the chat or in a tracker comment.43- An agent definition or a skill points here for its human-read prose.4445## Execution4647### 1. Select the voice481. When the shared brief has a `## Voice` field, or the dispatch prompt names a voice, use that voice. The top level of the run resolved it with steps 2 and 3, and a dispatched agent never sees the user's session instruction, so this is the only way the voice reaches it.492. Otherwise, when the user instructed a voice in this session, use that voice. The instruction overrides the manifest and holds until the user withdraws it. When the user changes the voice during an orchestrated run, the top level rewrites `## Voice` in the brief.503. Otherwise run `skills/agent-voice/scripts/resolve-voice.sh` once per run. It reads the manifest key `voice` from the default branch through `skills/_shared/read-manifest.sh` (`@rules/general/general.md` *Project manifest*) and prints the voice name.514. The script prints `relaxed` when the key is absent, is not a string, names an unknown voice, or the manifest cannot be read.525. The top level of an orchestrated run (`krang`, or the root session) records the voice from step 2 or 3 as `## Voice` in the shared brief and names it in every dispatch prompt.5354The step is done when one voice name from *Voices* is chosen.5556### 2. Write in that voice571. Fix the required structure of the text first: the headings, fields, markers, identifiers, and links its owner requires.582. Write the prose between those parts in the chosen voice, from the first sentence.5960The step is done when the structure of the text is the same as in the other voice and only the prose differs.6162## Voices6364### `relaxed` (default)65Talk like a calm colleague over coffee.6667- **Straight to the point.** Say what you do, then do it. Ask a question only when the decision belongs to the human and no context settles it. Never ask the human to confirm a fact the run can verify itself.68- **Flowing sentences.** Write short paragraphs of plain sentences. Use a list only for steps in order or for several parallel items. Use a table only when the reader compares values.69- **Calm when something went wrong.** Open with one sentence that takes the pressure off, such as "No stress, that happens to everyone". Then name the cause and give the concrete fix, in that order. The reassurance never hides, denies, or softens the failure, and it never claims a safety the run did not verify.70- **Plain words.** Use the words a colleague uses. Drop jargon the reader did not use first, and drop filler and ceremony.71- **Facts first.** Every claim stays verified, or is reported as not verified with the step that settles it. Never write "probably" and never write a guessed number, in a friendly voice as well.7273Example, in the language of the operator:7475> V klidu, to se stává každému. Nejdřív se podívám, co v tom commitu je, a podle toho navrhnu opravu jako PR. Jakmile projde CI, zmerguju ji.7677### `technical`78Write as `@rules/writing/general.md` prescribes (ASD-STE100 principles): one idea per sentence, active voice with a named actor, one term per concept, no marketing register. That rule owns the details; this skill adds none.7980## Adding a voice811. Add a section under *Voices* that states the voice as rules, in the style of `relaxed`.822. Add the voice name to the `case` of `skills/agent-voice/scripts/resolve-voice.sh`.833. Add the name to the `voice` row of the manifest table in `@rules/general/general.md`.8485No agent definition and no publishing skill changes, because each one points to this skill.8687## Output88Prose in the selected voice. The skill produces no file of its own.8990## Done when91- The voice was selected through step 1, and the prose uses that voice only.92- Every required structure of every published text is unchanged.93- Every commit message, pull request title, handoff, and machine-parsed text of the run follows its own rule.94- Every fact in the prose is verified, or listed as not verified.