For Us, Straight to the Point. For Agents, Everything.

Agents now write most of my pull request descriptions, review replies, and issues. They write well, but they write a lot.

A long pull request description doesn’t get read. The reviewer skims the first lines, scrolls, and approves or asks a question the text already answered. But the next agent that picks up the thread wants all of it: what changed, why, what was tested, and what was not.

So every post has two readers. I stopped trying to write for both in one block of text.

Two Sentences on Top, the Rest Folded

Every post I publish from an agent now has the same shape:

1. An opening of one or two sentences, for people. The skills call it the lead.
2. A divider.
3. The full text in a collapsed block, for agents, or for anyone who wants everything.
4. A footer that names the skill that wrote it.

On GitHub, the block is a <details> element. On Linear, an issue tracker many software teams use, it’s a >>> block. Either way, the reviewer sees two sentences and a closed box.

Here is a real one, my pull request to the Homebrew extension for Raycast. The opening says what changed and what to review. The before and after images sit right under it, and everything else is folded away.

One catch: GitHub’s command-line tool uploads images only for people who can write to the repository. When you send a pull request from your fork to someone else’s project, you usually can’t. So the skill posts the table with a placeholder in each image cell and tells you which file goes where. Then you paste the images in the browser, where any contributor can add them.

Before	After
📎 Paste dia-before.png here	📎 Paste dia-after.png here
dia lists AirMedia first. Dia is about three pages down.	dia lists Dia first, then names that start with "dia".

Some posts are so short that a folded block would only repeat them. A reply to a review comment can be one line: “Fixed in b72e019. Please review again.” Then the agent posts just that line, with no divider, no folded block, and no footer.

The Opening Says What to Do

The opening says two things: what changed, and what the reader must do, for example “Please review the backoff values.” or “Please check the error color in dark mode.” If there is nothing to do, it only says what changed.

The agent writes the opening last, after the details are done. Written first, it turns into an introduction: “This PR adds…”. Written last, it’s a summary of something that already exists, and the action is easy to see.

The idea of starting with the next action comes from i-have-adhd. It works for people with or without ADHD. A busy reviewer has the same problem.

The Details Stay Complete

The collapsed block doesn’t summarize. If the repository has a pull request template, the block follows it, heading by heading. The maintainers wrote that template for a careful review, so it stays. It just moves out of the way. Without a template, the skill uses its own headings: Summary, Why, Changes, How it was tested, and Not tested (and why).

So a reviewer has two ways in. For a quick look, the opening and the screenshots are enough: what changed, what it looks like, and what to check. For a careful review, they open the code and the block, and find the template they asked for, filled in.

“Not tested” matters most. Green CI proves only what CI runs. An agent that says what it did not check gives the reviewer something real to look at. The skill adds this section even when the template doesn’t ask for it.

Because people don’t read the block by default, it can be as long as it needs to be. Nobody has to choose between a short post and a complete one.

Opened, the Homebrew pull request follows Raycast’s template: Description and Screencast, then the checklist at the end. Between them, the skill added How it was tested, with the exact commands and results, and Not tested (and why).

Your Languages, in Your Order

Not everyone on a team reads English comfortably, and not everyone writes in it. So the skills write in your languages: a first language, shown on top, and any others under it.

The first time you run one, it asks two questions in the language you write to it in, and saves your answers as the default:

Which language should your posts lead with?

english

Add other languages under it?

yes: japanese

After that, I change it for one post in plain words: “only english”, “japanese first”, “use only portuguese”. When Japanese comes first, the English original comes after 原文:, so readers know which text is authoritative.

I tried it on the Homebrew fix from earlier. The real pull request stays in English, so I did not disrupt the open-source project I was contributing to. On my fork, I opened the same change in English and Japanese, and filed a Linear issue for it the same way.

The text in my own language is written first, and every translation comes from the finished text. A translation of a draft drifts from the final version.

Before posting, a small script checks the text. In every language, it limits sentence length: 30 words, or 80 characters in languages written without spaces, like Japanese. It also checks English for em dashes, contractions, and vague words like “should”, and the parts of the format: the openings, the divider, the blocks, and the footer. It can’t check meaning, so the skill also asks the agent to reread the opening alone. The English rules build on simple-english and unslop.

One Skill, One Job

There are four skills, and each one owns one thing:

• post owns the text: the format, the language, the style, and the check.
• github and linear own the platform: the syntax and the commands.
• create-pr owns the pull request workflow: the exact range, the checks, the title, and before/after images right under the opening. It uses post for the text.

When GitHub changes how something renders, only github changes. When I want a better opening, only post changes. Later, a gitlab skill can sit next to github, and a jira skill next to linear, without touching the others.

The footer names the skill that ran, for example clins:create-pr. A reader who likes the result knows what to run to get the same thing.

Try It

The demo shows what each skill writes, with made-up examples on GitHub and Linear, including one pull request you can switch between four language pairs.

The skills are open source. Install them for any coding agent with:

npx skills add clins1994/skills

Issues and pull requests are welcome. The contributing guide lists a few starting points.