---
title: "The skills I use in every project"
description: "The 11 workflows I use across projects with Codex and Claude Code: evidence-based debugging, adversarial review, gauntlet loops, research, Git hooks, and AEO."
language: "en"
published: "2026-10-31T00:00:00.000Z"
tags: ["ai", "agents", "skills", "orchestration", "aeo"]
source: "https://www.rubenmarcus.dev/blog/portable-agent-skills"
translation: "https://www.rubenmarcus.dev/pt/blog/skills-dos-meus-projetos-para-codex-e-claude"
---

Someone asked which Codex skills I use for coding, automation, and agents doing more complex analysis. I went through my setup. Some lived in the global skills directory. Others were buried inside projects, Git hooks, and Ralph Starter's source code.

That inventory became [agent-skills](https://github.com/rubenmarcus/agent-skills): an open collection of **11 workflows for Codex and Claude Code**, with instructions, examples, and documented sources.

A skill is a folder with a `SKILL.md` file and optional references or scripts. Its name and description help the agent choose it; the instructions describe how to carry out the task and what evidence to collect. You can read those files before giving the workflow access to your project.

[Addy Osmani](https://github.com/addyosmani/agent-skills) and [Matt Pocock](https://github.com/mattpocock/skills) already maintain collections in this format. I liked the distribution: small folders you can read before installing. I wrote generic versions of my own workflows, then compared the instructions with theirs.

## Where these workflows fit

Several methods overlap. [Matt's diagnosing-bugs](https://github.com/mattpocock/skills/blob/a496f5513d4a4cf889bc48e189e579f4b0bdf6aa/skills/engineering/diagnosing-bugs/SKILL.md) asks for a reproduction and confirmation that a test mutation took effect. [Addy's doubt-driven-development](https://github.com/addyosmani/agent-skills/blob/eb07f19f52c2669f2364897aaa293e2aaddd7b1c/skills/doubt-driven-development/SKILL.md) separates artifact review from the builder's justification. I want those decisions in my tasks too.

I kept the 11 as the selection I use across projects. Two have particularly concrete roots here: AEO against the aeo.js API, and Gauntlet rounds built around captures and critiques of game maps. If you already have a review workflow that works, you can try one of those two first.

The README gives each skill a scenario, a prompt, and an expected artifact, alongside links to complementary collections. Comparing instructions helps you choose a workflow; measuring its effect requires running the same task with and without it.

## I started with recurring errors

A useful skill changes a decision during the work. I selected mine by looking at the failures each workflow tries to prevent.

While debugging, an agent can fix a similar module and leave the user's reported path untouched. During review, it can repeat the builder's justification. In an implementation loop, it can mistake repeated attempts for progress.

Those failures became four concrete instructions:

| Skill | What I ask the agent to do |
| --- | --- |
| `evidence-driven-debugging` | Reproduce the scenario and trace the path through the UI, request, response, and rendering. |
| `critical-adversarial-review` | Review a specific revision and support each finding with a location, trigger, and impact. |
| `gauntlet-loop` | Establish a baseline, implement, critique, search for regressions, and record each round's decision. |
| `quality-gates` | Check whether the acceptance gate measures the intended behavior. |

I'm particularly fond of that last one. A regression gate earns credibility when you apply a deliberately broken change and watch it fail for the expected reason. If the change never took effect, the experiment is inconclusive. If a measurement is missing, the result remains unknown.

A real example from the game: one Gauntlet round made the brightest map darker than the night scenes. The capture agent used the darkest frame as its exposure reference. The rule changed to the average of eight frames. I wrote about it in [Inside the Gauntlet loop](/blog/inside-the-gauntlet-loop).

The FPS visual criteria stay in the original project. The public version carries the method: define the acceptance bar, separate building from evaluation, and keep each round's evidence.

## A critical reviewer needs room to disagree

For adversarial review, the reviewer gets the artifact, its contract, and the context needed to assess the change. It needs to reach its own judgment.

The output I want is simple: where the problem is, which input triggers it, what should happen, what happens, and how to verify it. A reproduction that hasn't run yet stays labeled as a hypothesis.

I also removed any incentive to fill a findings quota. Asking for ten bugs in a small change puts pressure on the reviewer to invent defects. It can finish with no demonstrated problem and explain which checks remain pending.

You can try a bounded task:

```text
Use critical-adversarial-review to review the change between BASE and HEAD.
The endpoint must preserve pagination when the filter changes.
Read the diff and callers. Do not edit files.
For each finding, provide the location, triggering input,
expected result, observed result, and a minimal reproduction.
Label hypotheses that have not been executed. Zero findings is acceptable.
```

Replace `BASE` and `HEAD` with actual revisions. The prompt ties the analysis to a change and an observable behavior. The skill supplies the review contract and its boundaries.

## Research includes knowing what a post supports

I use social media research to find reports, examples, and problems that documentation leaves out. That practice went into `source-backed-research` alongside technical research.

Each source needs a record of what it supports. A post can document one person's experience. Likes measure one kind of interaction with that content. A manually selected sample needs its selection criteria recorded.

When comparing tools, I combine those reports with documentation and source code where available. I record the date, version, and distinction between observation, a source's claim, and my own inference. That gives me a way to revisit a conclusion when the product changes.

The question that started the inventory also mentioned credit analysis. The package can help organize sources and challenge recommendations, but that use needs domain requirements and evaluation. None of the 11 skills has been validated as a credit decision system.

## What I extracted from Ralph Starter

[Ralph Starter](https://github.com/rubenmarcus/ralph-starter) already has its own skills, several tied to product integrations. For this collection, I extracted three methods from its executor and coordination code:

| Skill | The decision it organizes |
| --- | --- |
| `spec-to-plan` | Which observable behavior defines completion? |
| `validated-coding-loop` | Which evidence guides the next attempt, and when should the loop stop? |
| `agent-worktree-orchestration` | Who can write where, and how should candidates be compared? |

The inspection turned up a useful gap between intent and implementation. In [`swarm.ts` at the inspected revision](https://github.com/rubenmarcus/ralph-starter/blob/ee9c7946c386bb9cecc4001a052e29ffa53f8f9a/src/loop/swarm.ts), the comment describes an LLM judge for `consensus` mode. The code selects among successful results by iteration count.

That's why the skill asks for an explicit acceptance rubric. Fewer iterations can tell you something about cost; correctness needs its own evidence. The [Ralph Starter article](/blog/automating-entire-workflows-with-ralph-starter) explains the executor behind these methods.

The `multi-agent-collaboration` skill came from a different context: my ECDSA work. I generalized the handoffs, independent reproduction, and resolution of conflicting hypotheses. Circuit details and domain metrics stayed in the original project.

Collaboration belongs in tasks that allow parallel agents. For a small fix, preparing the handoff and reconciling results can cost more than it saves. The package keeps that choice within the task's scope.

## AEO with aeo.js made the collection too

The `aeo` skill uses [aeo.js](https://github.com/rubenmarcus/aeo.js) to audit and implement a site's public discovery surfaces: crawler policy, canonical URLs, sitemap, machine-readable content, and structured data. AEO stands for Answer Engine Optimization: preparing that content for systems that generate answers.

It starts with the existing configuration. If another integration already generates `robots.txt` and the sitemap, we need to preserve that owner and disable overlapping generators. Access policy also needs to keep reflecting the project's intent.

Authentication and authorization for restricted content stay in the application. Files such as `robots.txt` and `llms.txt` describe crawler policy and discovery; they don't enforce access control.

During validation, generating a file and serving a response are separate steps. A `schema.json` in the build needs another check of how the data reaches the page. The audit score describes the tool's criteria; answer citations and traffic gains need their own observations.

Even the version deserves inspection. At the [reference revision](https://github.com/rubenmarcus/aeo.js/tree/9955ce8d9ee77d9ca0c6cd4e26e047a1081697a1), `package.json` says `0.0.17`, while the CLI's displayed version constant says `0.0.14`. I recorded the commit alongside the commands to make the reference reproducible.

## Three tasks, with and without a skill

I prepared three synthetic tasks: repair a gate that accepts missing observations, reduce data reads in a route, and repair EN/PT discovery with aeo.js. Each pair uses fresh sessions of the same Claude Code client, with the same model, tools, and limits. One session receives the skill text and its references; the other receives only the task.

The first round exposed a problem in the task instructions. Five of the six sessions requested shell or Git commands the environment didn't permit. They remain unscored under the frozen rule. I froze a second version explaining the available Node commands, with identical guidance in both arms and unchanged checks. The [pilot report](https://github.com/rubenmarcus/agent-skills/blob/main/evals/pilot/REPORT.md) keeps those earlier attempts.

All six second-round sessions completed without denied commands:

| Task | No supplied skill text | Supplied skill text |
| --- | --- | --- |
| Release gate | 5/5 checks | 5/5 checks |
| Participant summary | 4/4 checks, 400 reads | 4/4 checks, 400 reads |
| EN/PT discovery | 4/5 checks | 5/5 checks |

In the AEO task, the baseline kept the draft in `config.routes` and disabled discovery generators. The unpublished page still returned HTTP 200. The session given the skill removed that route, and the probe received 404. Both arms preserved robots and sitemap. That's one observed difference under a fixture that requires excluding unpublished content; the other two cases tied. One execution per arm does not establish a general effect.

These cases exercise instructions supplied directly to Claude Code. Automatic skill discovery, Codex behavior, and visual review of game maps need their own runs. Matt's and Addy's collections were outside the experimental arms.

## How to try one skill

The package shares the same `SKILL.md` files between agents. Each folder contains a name, description, and instructions, with local references where the workflow needs them. Distribution metadata lives separately.

Install just the skill you need. From your target project's root, choose the command for your agent:

```sh
# Codex: only aeo in this project
npx skills add rubenmarcus/agent-skills --skill aeo --agent codex --copy
```

```sh
# Claude Code: only aeo in this project
npx skills add rubenmarcus/agent-skills --skill aeo --agent claude-code --copy
```

Replace `aeo` with any skill name from the README. These commands use the optional [Vercel skills CLI](https://github.com/vercel-labs/skills), which requires Node.js 22.20+. They copy only the selected skill and its supporting files into `.agents/skills/` for Codex or `.claude/skills/` for Claude Code. Review the destination and any overwrite warning before confirming.

The [README](https://github.com/rubenmarcus/agent-skills#manual-installation-of-one-skill) also explains how to copy a single folder manually, without the CLI. The Claude marketplace plugin is an optional bundle of all 11 skills. The `git-quality-hooks` example stays inactive until you configure it, preserving existing hooks.

With `aeo` available, I'd start with an audit that produces a reviewable artifact:

```text
Use aeo to audit this Astro site's English and Portuguese public pages.
Record the canonical origin, locales, installed aeo.js version,
and which integration owns robots.txt and the sitemap.
Inspect served canonicals and structured data. List the intended public
routes and any unpublished content appearing in discovery output.
Write the findings and smallest proposed change. Wait before editing.
```

The first result should be an inventory and a proposed change. For an implementation task, add the accepted scope and the responses you expect to verify after the build. The README has a matching scenario and expected artifact for every skill.

Structure, manifest, and isolated example checks passed during preparation. The pilot uses synthetic fixtures, including the AEO adapter lifecycle and local HTTP responses. A full behavioral evaluation of all 11 skills with Codex and Claude is still pending, with [scenarios recorded in the repo](https://github.com/rubenmarcus/agent-skills/blob/main/evals/scenarios.json).

Start with one recurring problem in your project. Write down the evidence that would make you accept the result, then run the skill on a small task. Keep the output, including cases where the agent ignores an instruction. Use that record to fix the next version.