Agent skills

Make your agent write more like a human

Mihailo SibonjicSoftware Architect1 August 2026, updated 7 August 2026

ai-agents · technical-writing

Ask a coding agent for a README, a status report, or a commit body, and you get AI slop that is hedged, padded prose, fond of the words AI overuses and closing lines that sound profound and say nothing. This article shows one way to replace that default with writing that reads more like an engineer wrote it, using the published style guide packaged as a skill.

Why does AI writing sound like AI?

Four habits mark machine-written technical prose, and each has a specific fix.

If a reader cannot disagree with a sentence, that sentence carries no information, and a summary built from such sentences tells you almost nothing relevant.

Why use Google's published guide

You can write your own rules and maintain them, and get a register that fits you exactly. The other option is a guide someone else maintains. The Google developer documentation style guide is public, and every rule in it has a URL. When you and the agent disagree about a sentence, you settle it by citation instead of by taste.

It is also opinionated enough to change what an agent writes. Here is how it sets the register:

The second row is a case the guide itself does not cover, an agent reporting on work it has just completed, which is covered by an extension in the section "Reporting your own work."

How a skill works, and what it costs

A skill is a directory, not a file. Its name is the skill name, kebab-case, and it holds a SKILL.md plus a references/ folder if you split it:

plain-prose/
├── SKILL.md          # required, and the only file that loads on trigger
└── references/       # optional, each file read only when its topic comes up
    ├── grammar.md
    ├── mechanics.md
    ├── ...
    └── word-list.md

SKILL.md carries a name and a description. The description is the trigger surface, so it has to name the situations rather than the topic, and only when it matches does the body of the file enter the context. You can also start it yourself, by naming the skill and handing it the work.

There is no mechanism behind the reference files. SKILL.md carries a table of topics and relative paths, under one instruction: read the file for the topic at hand, not all of them. The harness tells the agent which directory the skill lives in, the agent already has file access, and it joins the two. That is the entire loading model.

Nothing enforces the references/ name and nothing parses the table, so a path that does not exist fails silently rather than erroring.

So the cost comes in three tiers and only the first is always paid. The description is what the agent reads to decide whether the skill is relevant. On a match, the body of SKILL.md loads: that is the activation cost. A reference file loads only when a request touches its topic, which for most requests is never.

The skill this page publishes is SKILL.md plus eight reference files, 1,658 lines together, of which SKILL.md is 110. Activating it costs 110 lines and puts 1,658 within reach. What applies to every sentence goes in SKILL.md, and anything scoped to one topic goes behind a pointer.

The part that does the work

A rule the agent cannot check is a rule the agent will not follow. In practice the shortest section changes the output most. It is a checklist, run against a draft that already exists:

• Any sentence a reader could not disagree with? Rewrite it as the claim it replaced.
• Outcome in the first sentence?
• Every heading a plain label, in sentence case?
• Any word from the slop list, any just, simply, leverage, robust, seamless?
• Passive voice where the actor matters?
• Any superlative or guarantee you cannot support?
• Anything asserted that you did not actually check?
• Anything you skipped that you have not admitted?

Every line is a yes or no question about text already in front of it, which is why it holds up against a real request.

The skill file

Where the directory goes depends on the tool, and on whether you want it everywhere or in one repository:

.agents/skills/ is the shared root: the tools on the last row all read it, and Copilot and Goose read .claude/skills/ as well, so a repository already set up for Claude Code is partly portable without moving anything.

Download the skill and reference files and place them in the appropriate location depending on your agent of preference.

Always read the skill before you install and use it.

SKILL.md

The eight reference files

The single file covers every sentence. The eight reference files exist because most style rules are scoped to one kind of writing, and loading all of them for every request would waste context.

Each one extracts a part of the guide, so each is checkable against a URL. Each row below downloads one file, and the archive holds all eight under references/, which is where the skill layout wants them.

All eight, as a zip

All eight were extracted on 1 August 2026, and each section names the guide page it extracts.

The guide is revised continuously and it is the authoritative text, so open the cited page when a rule carries real weight.

Keep it about sentences

Notice that naming conventions for a stack, the difference between a package and a module, and which specification name is current are all real and useful, and none of them belong in a skill about prose. Vocabulary for one language changes on that language's schedule, and mixing it in means every request pays for rules it cannot use. It belongs in its own skill, which is also where it can be maintained by whoever knows that language.

The same split works upward. A prose skill governs the README while a language skill governs the code in the same commit, and neither has to know about the other. Split by material, not by project.

JUG.ba is the Java User Group for Bosnia and Herzegovina, launching fall 2026. Join the waitlist to get notified in time.

← All articles