Agent skills for planning, delivering, and publishing with agents

A skill is a folder with a SKILL.md. The frontmatter holds a name and a description, and the body has the instructions the agent loads when a task matches the description. I keep mine in pedrosatin/skills, and they work in Claude Code, Codex, Gemini CLI, OpenCode, and Cursor.

How the agent decides to use a skill

The agent reads only the name and description of every installed skill. The body enters the context when the description matches the request. A description should say what the skill does and when to use it, in a few lines. A long one costs context in every conversation, even when the skill is never used.

Some skills run only when I type the command. They set disable-model-invocation: true in the frontmatter: setup, board, to-spec, to-tickets, pr-loop, babysit-prs, teach, and show-me. pr-loop and babysit-prs merge PRs, so a loose phrase like “review these PRs” should not trigger them.

Install

There are two ways:

# skills.sh installs into every configured agent
npx skills add pedrosatin/skills

# or symlinks from a clone
git clone https://github.com/pedrosatin/skills.git
./skills/link.sh

link.sh creates ~/.agents/skills/<name> pointing at each folder under skills/. In an interactive session, it detects the other installed harnesses (Claude Code, Codex, and Gemini) and asks whether to link them too. ./link.sh --all links every detected harness without asking, and ./link.sh -y runs non-interactively in default mode. It skips directories that already exist and links that point outside the repository. Running it again after a git pull is safe, and the script removes broken links.

OpenCode reads ~/.agents/skills directly. Claude Code, Codex, and Gemini read through the symlinks the script creates in each one’s skills folder.

The planning flow

I start with /setup, which runs once per project, and then follow the order below when I begin a feature.

/setup prepares the project. It creates .scratch/ and the docs under docs/agents/, adds a block to AGENTS.md (or CLAUDE.md), checks graphify, and generates the Project Hub, a .scratch/index.html with the task board. It asks for confirmation before writing.

grilling makes the agent interview me about the plan. The questions arrive in rounds through the agent’s own question interface (AskUserQuestion in Claude Code), so I answer by picking options. Each round only holds decisions whose prerequisites are already settled. It ends when no open branch remains. At the close, it writes the settled terms to GLOSSARY.md and confirms with me, through the same interface, each decision that deserves an ADR.

/to-spec turns the conversation into a specification. It synthesizes what was already decided and asks no new questions. If the grilling close was skipped, it first writes to disk the terms and ADRs the conversation already settled. Before writing, it proposes the test boundaries: the external surfaces where the behavior will be observed. The file goes to .scratch/<feature>/spec.md.

/to-tickets splits the spec into vertical slices. Each ticket cuts through every layer (schema, API, UI, tests), can be verified on its own, and fits in one clean context window. Each declares the tickets that block it. The output is one file per ticket under .scratch/<feature>/issues/. The agent shows me the breakdown and publishes only after I approve it.

/board opens the Project Hub in the browser. If the board does not exist yet, the script points to /setup.

The delivery flow

/pr-loop works through backlog items one at a time. For each item, a subagent implements in an isolated worktree and creates a local commit. The main agent then runs clean-crap on the diff and tests the product behavior. It walks the UI flow, runs the CLI command, or calls the API. When the change is visual, it keeps before and after captures. From that result it drafts the PR description. A second subagent reviews code and prose in read-only mode, and a third applies the corrections. After the correction, the main agent tests the product again and refreshes the draft.

Push, PR, and merge stay with the main agent, which has the full conversation and my authorization. Asking for the loop authorizes the work up to opening the PR. Each merge needs a yes from me, unless I approved the whole batch beforehand with something like “merge everything”.

That is how I closed the PR that shortened the descriptions of the skills themselves. The loop ran the steps, the review asked me to restore one trigger and make the merge authorization explicit, and I merged only after answering yes.

clean-crap measures the complexity of each JavaScript and TypeScript function, joins it with LCOV coverage, and computes the CRAP score. When a function goes over the threshold, pr-loop sends a subagent to split the function or cover the untested branches before review. There are at most two correction rounds. On the third failure, the decision comes back to me.

pr-description writes the PR description from the diff and the checks that actually ran. In draft mode, it only writes a local file. In publish mode, it creates the PR or edits the one already open for the branch, with the captures attached as evidence.

/babysit-prs reviews every open PR in the repository, merges the safe ones, and leaves the risky ones as drafts with a comment.

/show-me draws sketches, call trees, and short diagrams for the question at hand. pr-description uses the same visual references when a PR needs a diagram.

Rules that apply to every commit

publication-hygiene runs before any commit, push, or PR action. It checks the title, body, trailers, authorship, and new files. It removes what reveals the tool used, such as co-author trailers, automatic footers, session URLs, and plan files. Author and committer remain me.

unslop-br edits Portuguese text. It cuts trailing gerunds, dashes, inflated adjectives, and the “not X, but Y” construction. I run it on PRs, READMEs, and posts before publishing.

validate-agent-config checks my agent setup. It verifies instruction files, symlinks, @ imports, and skill frontmatter. The script exits with code 1 when it finds an error.

writing-for-agents is a rubric for documents an agent reads, such as skills, AGENTS.md, and CLAUDE.md. I use it when I create or edit a skill.

What comes from other repositories

Part of the set comes from third parties and keeps its original license, listed in ATTRIBUTION.md. grilling, to-spec, to-tickets, research, teach, and writing-for-agents come from Matt Pocock’s skills. archify comes from tt-a1i/archify, graphify from Graphify-Labs/graphify, humanizer from blader/humanizer, and show-me from humanlayer/skills. Mine, under MIT, are unslop-br, publication-hygiene, pr-description, babysit-prs, pr-loop, clean-crap, validate-agent-config, setup, and board. pr-description adapts Matt Pocock’s pr skill.

Instructions are in English, except unslop-br, whose rules and examples are Portuguese. A few triggers and the Project Hub interface are also in Portuguese. The agent answers in the language of the conversation.

Getting started

Install, open a project, and type /setup. Then describe a feature and ask the agent to grill you. Once the decisions are settled, run /to-spec, /to-tickets, and /board to see the board. With the tickets ready, /pr-loop delivers them one at a time, and each PR goes out with its description and evidence of what was tested.

Repository · skills.sh