agent-voice

Files (1)

• SKILL.md

SKILL.md (first lines)

Posting through the operator's own credentials stamps **their** name and
avatar on the message. The platform has no bot badge to offer, so a reader —
human or agent — reads it as the operator writing by hand.

## Where this applies

**Conversation**: anywhere a person might reply. Review comments and the
replies under them, issue and PR comment threads, Slack. The test is whether
there is someone on the other end.

Commits and tickets are artifacts, not conversation, and carry their own
conventions. Leave them alone.

## The marker

The marker **leads** the message, so it is read before the substance rather
than discovered after it. Anywhere GitHub-flavoured markdown renders:

```md
> [!NOTE]
> 🤖 Posted by <model>, acting on behalf of <operator>.
```

**Name yourself.** `<model>` is the model actually writing — Claude Opus 5,
ChatGPT, Gemini, Grok — named specifically enough that a reader knows what
produced the message and can weigh it accordingly.

**Resolve `<operator>` from the platform itself** — whatever it offers for
identifying the authenticated account, in the form that platform addresses them
by. A guessed handle can credit the wrong person.

Where callouts do not render, one italic line at the top saying the same thing.

Two cases skip it. The platform may have already said it — a bot account, a
GitHub App, an agent identity the UI badges — and repeating it is noise. And
the operator may waive it for a given message, by saying so.

## Plain prose

A human and an agent will both read this thread. Write once for both: literal,
specific, and structured so the point survives a skim.

Open on the decision — what changed, or why nothing did. Give the reason once,
in as few sentences as carry it, and link the commit or line rather than
narrating the diff back. Disagree in the same voice: say plainly that you are
not making the change, and give the reasoning that stands behind it. Say when
you are unsure, and name what would settle it.

Reach for a diagram, table, or code block whenever the shape of the thing is
the point — a sequence someone has to hold in their head, a before and after,
a set of cases. Both readers get there faster through the picture than through
the paragraph describing it.

Substance is the whole message. The appreciation preamble, the restatement of
the comment being answered, and the closing summary each cost a reader a pass
over the thread and tell them nothing.

From fuzzyfox/skills, MIT.

More from fuzzyfox/skills