Skip to content
Alexandre Mahe
All posts

A minimal harness: reuse what exists, keep the agent in check

Mapping all development know-how into skills costs more than it returns. I reuse what exists, write only the high-value skills, and the harness is mainly there to keep the agent in check: permissions, tests, oversight.

Category
Note
Published
Reading time
4 min read
Tags
#agents#harness#skills#claude-code#pi

TranslationTranslated by AI from the original in French.Read the original

When an agent gets stuck, the easy fix is to add an instruction: a git skill, a Scrum skill, a skill per API. A few months later, the developer experience has turned into a museum of instructions to maintain, half of them out of date.

Those instructions aren't free. An ETH Zurich study shows that LLM-generated context files like AGENTS.md slightly lower agents' success rate and raise inference cost by more than 20%; written by developers, they bring a modest gain, at a higher cost. A frontier model already knows git and the common conventions. For a freelancer, productivity comes less from the number of instructions than from verified tools they know and can defend in front of a client.

I reuse what exists, and only write the skills that bring real value.

Using a skill wellLink to this section

A context file helps when it brings what the model doesn't know, and hurts when it repeats what it already knows. A skill follows the same rule, with one extra mechanism: the agent first sees only its name and description, and loads the rest only when needed. So the description decides whether the skill gets used; the main file stays short, and the details go into files it references. When I write one, the description says when to use it rather than what it is, and a deterministic step becomes a script rather than a procedure the model would have to follow to the letter.

For an API released after training, a skill isn't the best answer: Vercel measured that a compact index in the context did better than a skill the agent forgot to load. Documentation increasingly ships through llms.txt or MCP servers such as Context7.

Team skills, personal skillsLink to this section

Team skills describe what you can't guess by reading the code: how the team works with it, its conventions, its review steps. They live in the repository and serve everyone.

Personal skills carry my shortcuts, my methods, my way of breaking down a task, as long as they stay compatible with the project. They follow me from one project to the next and end up defining my own augmented developer agent.

It's also a matter of intellectual property. What comes from the company (its workflows, its conventions, its domain) belongs to it; what comes from my know-how belongs to me. Skills that distil years of method should help me, not feed the client's agents after the engagement: my personal skills stay in my own repository.

Client company Freelancer context responses constrains commits Agent and subagents LLM provider Repository: code, conventions,team skills Tests, CI, merge rights Personal skills,in their own repository Harness: permissions,sessions, oversight

Influencing the first inference as little as possibleLink to this section

Pi takes this logic all the way: a short system prompt and four tools, almost nothing before the user's prompt.

The Claude subscription only covers Claude Code and Claude.ai, not Pi. Nothing stops you from designing the harness with Pi, then porting it to Claude Code as skills, hooks and subagents, which keep the main session clean.

Security first, experience secondLink to this section

Context engineering decides what reaches the model at each step; the harness decides how the agent works, including the mechanisms that build that context.

My two priorities, in that order. Security first: strict permissions, tests and CI that check the result without adding anything to the prompt, and tools reviewed before they are reused. A third-party skill can contain scripts, an MCP server is code running with the agent's permissions, and either one can slip instructions into its context: I treat them as dependencies. Developer experience second: a repository that is pleasant to work in is easier to maintain, for the human and the agent alike. Between the two, prompts stay minimal.

A rule that must always apply has no place in a prompt. Claude Code hooks enforce it deterministically: block a command, format an edited file, run the tests before handing back control. Other agents have their equivalents, under other names.

The harness also covers moving from a local session to a remote one, talking to an agent running in a loop, and cost oversight, which goes through the proxy described in the post on client data.

Harness Contextwhat reaches the model PermissionsTests and CIOversight and costs Editor configurationLocal and remote sessionsTalking to the loop Tools and MCP serversSkills: team and developerSubagents

A comfortable agent in three blocksLink to this section

Working preferences, in a few lines of the context file. Mine:

Break the work into small tasks and parallelise what can be parallelised.
Run the tests at the end of each task, not after every change.
Keep a progress report up to date in PROGRESS.md.
Ask a question rather than guess at a vague requirement.

Permissions, in .claude/settings.json, versioned with the repository; the documentation details the syntax. Pi has none by default; extensions add them.

"allow": ["Bash(npm run test *)", "Bash(git diff *)", "Bash(git commit *)", ...],
"ask":   ["Bash(git push *)", "Bash(npm install *)"],
"deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)", ...]

A Read rule does not, however, block a cat .env run through the shell: the real protection is still having no secrets in the container, as in the first post.

Finally, a reputable skill collection rather than a home-grown library. Superpowers, by Jesse Vincent, covers design, TDD, debugging and review; Anthropic's official repository is the reference for writing your own. Review before installing, like any dependency:

/plugin install superpowers@claude-plugins-official   # Claude Code
pi install git:github.com/obra/superpowers            # Pi

Next post: context, meaning what the agent knows about the client, and its memory.