Designing Agents

Designing Agents

Overview

This repo has three kinds of artifacts that shape how an agent works. Each is authored, versioned, and invoked deliberately:

• Agent personas live in agents/.md. They define a role another agent adopts when it needs specialized review, audit, or analysis. Example: code-reviewer, security-auditor, test-engineer.
• Skills live in skills//SKILL.md. They define a workflow — a repeatable process with gated steps, anti-rationalization guardrails, and verification. Example: spec-driven-development, test-driven-development, context-engineering.
• pi harnesses live in .pi/harnesses//. They define a session environment — a TypeScript pi extension that reshapes the whole session: setting UI surfaces, gating tool calls, registering new tools or commands, or orchestrating sub-agents. Example: agent-hub, damage-control, coms.

Personas and skills are prose that change an agent's judgment. A harness is code that changes the agent's environment — what it can do and what it sees. All three fail the same way: a persona that reads like general advice gets cited but ignored; a skill that skips its guardrails becomes a suggestion; a harness built without studying the existing ones collides with pi's auto-discovery or fights another extension. This skill is the workflow for authoring any of the three so the result measurably changes behavior.

When to Use

• Creating a new persona file in agents/ (reviewer, auditor, domain specialist)
• Creating a new skill directory in skills/ (a process, checklist, or workflow)
• Creating a new pi harness in .pi/harnesses/ (a footer, focus gate, safety check, orchestrator, or messaging layer)
• An existing persona, skill, or harness is vague, overlaps another, or is being ignored in practice
• A recurring review, workflow, or session-shaping need has emerged and deserves its own artifact
• Rewriting an older artifact to align with current writing standards

NOT for:

• One-off prompts — just write the instruction inline.
• Claude Code .claude/agents/ sub-agents — those use a different frontmatter (tools, model, color). The persona workflow in this skill still applies; only the frontmatter shape differs.
• Reference material (long checklists, pattern catalogs) — those belong in references/, not in skills or personas.
• An always-on pi utility extension under .pi/extensions/ — this skill covers the selectable, mutually-exclusive harnesses under .pi/harnesses/. Adding an auto-discovered utility is a different decision; see docs/pi-extensions.md.

The Workflow

This workflow is abstracted from the three reference personas (agents/code-reviewer.md, agents/security-auditor.md, agents/test-engineer.md), from docs/skill-anatomy.md, and from the ported harnesses under .pi/harnesses/ (catalogued in docs/pi-extensions.md). Do not advance to the next step until the current one is settled.

1. Choose the target type

Ask: is this a role the agent should adopt, a process it should follow, or an environment it should run inside?

| Target | Choose when | Output | |---|---|---| | Persona | The agent needs to evaluate or review through a specific lens (correctness, security, test strategy, accessibility, migration safety…) | agents/.md | | Skill | The agent needs to follow a repeatable process with gated steps, verification, and anti-rationalization guards | skills//SKILL.md | | pi harness | The session itself must change — footer, status, a blocking gate on tool calls, a new tool or /command, or sub-agent orchestration | .pi/harnesses// (a directory) |

If more than one applies, split them: a harness can enforce a workflow that a skill describes, and a persona can supply the lens. Do not merge the formats — each has its own structure and verification.

2. Clarify intent

Ask the requester for:

• One-sentence purpose — what does this artifact do that a general agent cannot?
• Primary tasks or steps — 2-4 concrete things it will be invoked to do.
• Explicit non-goals — what it should refuse or redirect.
• Invocation trigger — when should the calling agent delegate to this vs. handle the task itself? For a harness: how is it launched, and does it stack with another harness?

Do not proceed until the one-sentence purpose is locked. If the requester cannot state it in one sentence, the artifact is not ready to exist yet.

3. Scan for overlap

Read every existing artifact of the target type:

• For a persona: every file under agents/.
• For a skill: every skills/*/SKILL.md (start with the Quick Reference table in skills/using-agent-skills/SKILL.md).
• For a harness: the catalog table in docs/pi-extensions.md, then the README.md of each .pi/harnesses/* that looks close.

If the new artifact overlaps an existing one by more than ~30% (same scope, same output, same session surface), choose one of:

• Extend the existing artifact
• Tighten scope so the new artifact covers ground the existing one does not
• Abandon the new artifact — duplication is worse than absence

Two personas covering similar ground produce inconsistent reviews. Two skills produce conflicting advice. Two harnesses that both replace the footer, or both register the same CLI flag, collide at load time.

4. Pick a kebab-case name

Follow the existing pattern:

• Persona: ` or - (code-reviewer, security-auditor, accessibility-reviewer`)
• Skill: verb-phrase or noun-phrase describing the process (spec-driven-development, context-engineering, planning-and-task-breakdown)
• Harness: short noun describing the session surface (agent-hub, damage-control, coms)
• Bad for any: helper, assistant, smart-agent, codeReviewer

The name must match across: the directory/file name, the frontmatter or package.json name, and the H1 title (persona/skill) or README H1 (harness).

5. Write the discovery surface

How the artifact is found and delegated to.

Personas & skills — the frontmatter description. Action-oriented; says when, not how.

• Persona structure: . Use for .
• Good: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
• Skill structure: . Use when .
• Good: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

Harnesses — a harness has no frontmatter. Its discovery surface is the README.md (H1 matching the directory name, a one-line subtitle, a "What it does" section) plus the catalog row in docs/pi-extensions.md. That row is what an agent actually scans — write it as | name | Category | one-line what-it-does | run command |.

Bad for any (avoid):

• Starts with "Helps with…" or "Assists in…" — vague, not delegation-friendly.
• Summarizes the full workflow — the description says when, not how.
• Over 280 characters — gets truncated in discovery.

6. Draft the body

This step branches by target type.

6a. Persona body (four-block structure)

Used by every persona in agents/. See the Persona Template below.

# 

You are a   focused on . Your role is to . 

## 

## Output Format

## Rules
1. 

6b. Skill body (per docs/skill-anatomy.md)

Every skill in this repo follows the same section order. Do not invent new section names. See the Skill Template below.

# 

## Overview

## When to Use
- 
- NOT for: 

## The Workflow (or Core Process / Steps)

## Common Rationalizations
| Rationalization | Reality |
|---|---|
|  |  |

## Red Flags
- 

## Verification
- [ ] 

Skills have one mandatory section personas don't: Common Rationalizations. This table is the anti-rationalization lever that prevents the agent from talking itself out of following the process. Personas don't need it because a persona is a lens, not a workflow with skippable steps.

6c. Harness body (a TypeScript pi extension)

A harness is code, not prose. It is a directory with three files:

• index.ts — the extension: export default function (pi: ExtensionAPI) { … }
• package.json — four fields: name, private: true, type: "module", main: "index.ts"
• README.md — the discovery surface (see step 5)

The index.ts hooks pi session events (session_start, tool_call, agent_end, input, before_agent_start, …) and may register tools, commands, footers, widgets, and status text. Read pi-harness-authoring.md in this skill's directory before writing any harness — it documents the ExtensionAPI surface, the directory anatomy, the index.ts and README.md templates, and which existing harness to copy the closest pattern from. Do not write a harness from memory of this section alone.

A harness also has wiring steps that personas and skills do not — step 9 covers them: a just ext- recipe in the justfile and a row in the docs/pi-extensions.md catalog.

7. Apply prompting-patterns

Before finalizing, read references/prompting-patterns.md and check the artifact against these sections. This applies to all three types — for a harness, to the prose it injects (system-prompt text, tool descriptions, block reasons), not the TypeScript itself.

• §2.2 — Positive instructions, not prohibitions. Rewrite every "don't do X" as "do Y".
• §2.3 — Explain why for any non-obvious rule. One short clause is enough.
• §2.4 — Scan for contradictions. "Be thorough" + "be concise" must be resolved.
• §2.5 — Remove ALL-CAPS and reward/punishment language ("CRITICAL", "you MUST", "never ever").
• §3.1 — First sentence sets the role (persona) or the overview (skill). Make it specific, not generic.
• §6.4 — Include anti-overengineering guards if the artifact produces or modifies code.

8. Minimize surface area

Cut every sentence that does not change behavior. Read each rule and ask: "If I removed this, would an invocation of this artifact produce different output?" If no, remove it.

• A 90-line focused persona beats a 200-line comprehensive one.
• A 150-line focused skill beats a 300-line exhaustive one.
• A harness that does one thing beats one that does five — stack two harnesses instead of merging them.
• The comprehensive version gets skimmed and its rules get skipped.

9. Write the file(s)

• Persona → agents/.md.
• Skill → skills//SKILL.md (create the directory; supporting files only if the skill exceeds ~300 lines or needs separate reference material).
• Harness → .pi/harnesses// with index.ts, package.json, and README.md. Then add a just ext- recipe to the justfile under the matching category header, add a catalog row to docs/pi-extensions.md, and add any new runtime dependency to .pi/harnesses/package.json. Never place a harness under .pi/extensions/ — pi auto-discovers that directory and would load every harness at once.

10. Verify

Walk the Verification section below. Use the shared checklist plus the target-specific checklist. Do not ship an artifact that fails any item.

Persona Template

Minimal skeleton — keep placeholders in angle brackets until the content is concrete.

---
name: 
description:  that . Use for .
---

# 

You are a   focused on . Your role is to . 

## 

### 1. 
- 
- 

### 2. 
- 

### 3. 
- 

## 

| Severity | Criteria | Action |
|---|---|---|
| Critical |  |  |
| Important |  |  |
| Suggestion |  |  |

## Output Format

\`\`\`markdown
## 

**Verdict:** 

### 
- [file:line] 

### 
- [file:line] 

### What's Done Well
- 
\`\`\`

## Rules

1. 
2. 
3. 

Skill Template

Minimal skeleton — the canonical format is documented in docs/skill-anatomy.md; do not deviate from its section order.

---
name: 
description: . Use when .
---

# 

## Overview

## When to Use
- 
- 

**NOT for:** 

## The Workflow

### 1. 

### 2. 

### 3. 

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "" |  |
| "" |  |

## Red Flags

- 
- 

## Verification

After completing the workflow, confirm:

- [ ] 
- [ ] 
- [ ] 

Harness Structure

A harness is a directory, not a single file. The ExtensionAPI surface, the index.ts skeleton, the package.json shape, the README.md template, and the justfile / catalog wiring are all in pi-harness-authoring.md alongside this skill — that file is the harness equivalent of docs/skill-anatomy.md. Do not start a harness without reading it; copy the closest existing harness it points you to rather than writing index.ts from memory.

Common Rationalizations

| Rationalization | Reality | |---|---| | "I'll make it general-purpose so it's reusable everywhere" | General artifacts get cited but never change behavior. Narrow scope creates measurable change. Scope is a feature, not a limit. | | "I'll skip the Output Format section — the agent will figure it out" (persona) | Without a template, outputs drift across invocations and become uncomparable. Reviewers cannot triage findings that don't share a shape. | | "I'll skip the Common Rationalizations table — the steps are obvious" (skill) | Every step that gets skipped had an excuse attached. The table is the only place in the skill that directly blocks those excuses. Skipping it is how skills become suggestions. | | "I'll skip the Verification checklist — the user will know when it's done" (skill) | Without evidence requirements, 'seems right' becomes the completion signal. The checklist is what forces proof. | | "I'll drop the harness in .pi/extensions/ so it loads automatically" | pi auto-discovers .pi/extensions/ and loads everything there at once. Most harnesses are mutually exclusive — footers fight, duplicate CLI flags abort startup. Harnesses live in .pi/harnesses/ and load explicitly; the supported stack is damage-control before agent-hub. | | "I'll write the harness index.ts from memory — I've seen the pattern" | The ExtensionAPI surface is specific and unforgiving; a misspelled event name fails silently. Read pi-harness-authoring.md and copy the closest existing harness. | | "I'll skip the harness README and catalog row — index.ts is the real artifact" | A harness with no row in docs/pi-extensions.md is undiscoverable; no agent will load it. The README is its discovery surface — the same role frontmatter plays for a skill. | | "I'll copy an existing artifact and tweak it" | For prose artifacts, copy-paste creates silent duplication and drift — read the existing files to learn the pattern, then write fresh. For a harness, copying the nearest index.ts is the recommended start; just rename it cleanly and cut what you don't use. | | "I don't need to read prompting-patterns, I know how to write prompts" | Every author thinks this. The reference exists because recurring, measurable mistakes happen anyway. Spend 3 minutes skimming §2 and §6. | | "I'll add every tool and capability — flexibility is good" | This repo's agents/*.md don't declare tools at all; scope creep happens through the prompt body. Skills and harnesses that try to cover many domains lose their force. Bloated artifacts get skimmed. | | "The purpose is hard to state in one sentence because it covers a lot" | If you cannot state it in one sentence, the artifact covers too much. Split it or scope it down. | | "I'll leave the rules/steps section light so the artifact can be flexible" | Empty Rules or vague steps become empty behavior. The specifics are what differentiate this artifact from a general agent. | | "My skill is mostly reference material — I'll inline a 200-line checklist" | Reference material belongs in references/. Skills are workflows, not reference docs. Move the long content out and cite it. |

Red Flags

Shared (all three types):

• Descript

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chankov
• Source: chankov/agent-fleet
• License: MIT

Install and usage instructions live in the source repository linked above.