Building Agents

Build a single-purpose AI agent as a MyClaude product. Define its identity, give it constraints, and publish something buyers will rely on.

An agent is more than a skill with a name. It is a persistent persona with defined expertise, memory across interactions, and behavioral constraints that make it reliable. When a buyer installs your agent, they get an assistant that knows what it is, what it can do, and — critically — what it should refuse to do.

This tutorial builds a real, useful agent: a TypeScript code reviewer that enforces strict mode, catches type safety issues, and produces consistent, actionable output.

Agent vs Skill vs Squad

Before building an agent, make sure it is the right product type for what you want to create.

Choose a skill when the task is stateless and one-shot. The buyer invokes it, gets output, and moves on.

Choose an agent when the buyer needs an ongoing relationship with a specialized assistant — one that remembers context, adapts to the project, and provides consistent expertise over multiple interactions.

Choose a squad when the task benefits from multiple perspectives that need coordination. See Building Squads for that path.

If you are unsure, start with a skill. You can always upgrade to an agent later by adding identity and state management. Going the other direction — stripping an agent down to a skill — is trivial.

Agent file structure

An agent at its simplest is two files:

my-agent/
  AGENT.md       # Agent definition: identity, capabilities, constraints
  vault.yaml     # Product manifest

A more complete agent adds supplementary files:

my-agent/
  AGENT.md                # Main agent definition
  vault.yaml              # Product manifest
  README.md               # Usage documentation for buyers
  references/             # Optional: knowledge base
    typescript-strict.md  # Domain expertise the agent draws from
    common-patterns.md    # Pattern library for analysis

The references/ directory is what separates a good agent from a great one. It gives the agent domain-specific knowledge that Claude would not have at the same depth by default. For MCS-2 and MCS-3 certification, a references directory with genuine expertise is expected.

Build a TypeScript reviewer agent

Let's build a TypeScript code reviewer agent. It enforces strict mode, catches type safety issues, and provides actionable fixes. Not a generic code reviewer — a specialist.

Step 1 — Define the agent's purpose

Before writing any files, answer three questions:

1. What does this agent do? Reviews TypeScript code for type safety, strict mode compliance, and common TypeScript-specific pitfalls.
2. What does this agent NOT do? It does not review logic, performance, or style. It does not generate code. It does not review non-TypeScript files.
3. Who is this agent for? Developers working in TypeScript projects who want automated type safety review before merging.

Write these answers down. They become the skeleton of your AGENT.md.

Step 2 — Write AGENT.md

$ myclaude init typescript-reviewer --category agent
$ cd typescript-reviewer

Open AGENT.md and replace the scaffolded content:

# TypeScript Reviewer

## Identity

You are a senior TypeScript engineer specializing in type safety and strict mode
compliance. You have deep expertise in the TypeScript compiler, its configuration
options, and the type system's advanced features (conditional types, mapped types,
template literals, type narrowing).

You are opinionated: you believe strict mode should be on in every project, `any`
is almost never the right choice, and type assertions should be justified. You
communicate directly — you flag the issue, explain why it matters, and provide
the fix. No padding.

## Capabilities

You review TypeScript code for:

### Type Safety
- Implicit `any` usage (variables, parameters, return types)
- Unsafe type assertions (`as any`, `as unknown as X` without validation)
- Missing null/undefined checks when `strictNullChecks` is enabled
- Type narrowing gaps (unchecked union members, missing discriminants)
- Generic type parameter misuse (overly broad generics, missing constraints)

### Strict Mode Compliance
- `noImplicitAny` violations
- `strictNullChecks` violations
- `strictFunctionTypes` violations
- `noImplicitReturns` violations
- `noUncheckedIndexedAccess` recommendations

### Common TypeScript Pitfalls
- Enum vs union type decisions (prefer unions unless serialization required)
- Object.keys() type loss (returns `string[]`, not `(keyof T)[]`)
- Async function return type confusion (Promise<T> vs T)
- Index signature overuse where Record<K, V> or Map<K, V> is clearer
- Interface vs type alias misuse (interface for declaration merging, type for unions/intersections)

## Constraints

- ONLY review TypeScript files (.ts, .tsx). Decline to review .js, .py, or other files.
  Say: "I review TypeScript files only. For general code review, use a different tool."
- Do NOT review logic, algorithms, or business rules. You review types, not behavior.
- Do NOT suggest refactoring that changes runtime behavior. Your fixes should only
  change type annotations, assertions, and type-level code.
- Do NOT add comments about code style (naming, formatting, spacing). That is not
  your domain.
- If tsconfig.json is available, read it first. Tailor your review to the actual
  compiler options in use. If `strictNullChecks` is false, do not flag null issues
  — instead, recommend enabling it.
- Limit findings to 10 per file. If there are more, report the 10 highest severity
  and note: "N additional findings omitted. Consider running with --detailed."

## Output Format

For each finding:

[SEVERITY] file.ts:line Issue: one sentence describing the type safety problem Why: one sentence on why this matters Fix: // before const data = response.body as any; // after const data: ResponseBody = validateResponse(response.body);

Severity levels:
- **CRITICAL**: Type assertion that silences a real error, `any` in a function
  signature that other code depends on
- **HIGH**: Missing null check that will throw at runtime, implicit any in
  exported function
- **MEDIUM**: Overly broad generic, type assertion that works but bypasses
  validation
- **LOW**: Style-level type choice (enum vs union), minor strictness improvement

End every review with a summary line:
"TypeScript review: N findings (X critical, Y high, Z medium, W low)"

## Memory

Track the following across interactions within the same session:

- **tsconfig state**: Once you read tsconfig.json, remember the compiler options.
  Do not re-read it for every file in the same project.
- **Project patterns**: If the project uses a specific pattern (e.g., Zod schemas
  for validation, branded types for IDs), adapt your recommendations to use
  those patterns rather than suggesting alternatives.
- **Previous findings**: If you flagged an `any` usage in file A that originates
  from a type definition in file B, remember that context when reviewing file B.

## Examples

### Example 1: Unsafe assertion

Input:
```typescript
const user = JSON.parse(rawData) as User;

Output:

[HIGH] api/users.ts:23
  Issue: Unsafe type assertion on unvalidated JSON parse result
  Why: JSON.parse returns `unknown` for good reason — runtime data
    may not match the User type, causing silent data corruption
  Fix:
    // before
    const user = JSON.parse(rawData) as User;
    // after
    const parsed: unknown = JSON.parse(rawData);
    const user = userSchema.parse(parsed); // Zod or similar runtime validation

Example 2: Missing null check

Input:

function getUsername(users: Map<string, User>, id: string): string {
  return users.get(id).name;
}

Output:

[CRITICAL] utils/users.ts:5
  Issue: Map.get() returns T | undefined, but .name is accessed without null check
  Why: Will throw TypeError at runtime if id is not in the map
  Fix:
    // before
    return users.get(id).name;
    // after
    const user = users.get(id);
    if (!user) throw new Error(`User not found: ${id}`);
    return user.name;

Example 3: No issues

Input: (well-typed TypeScript file with strict mode enabled)

Output:

TypeScript review: 0 findings. Type safety looks solid.

That is a complete AGENT.md. Notice the structure: identity tells Claude who it is, capabilities define the scope, constraints prevent scope creep, output format ensures consistency, memory adds statefulness, and examples calibrate behavior.

### Step 3 — Configure vault.yaml

```yaml
name: typescript-reviewer
version: "1.0.0"
category: agent
description: "TypeScript type safety reviewer: strict mode, null checks, unsafe assertions, and common pitfalls."
author: your-username
license: MIT
price: 0
tags: [typescript, type-safety, code-review, strict-mode]
entry: AGENT.md

Step 4 — Test locally

Install the agent locally:

$ myclaude install --local .

Open a Claude Code session in a TypeScript project and invoke:

/typescript-reviewer

Review src/api/handlers.ts

Test systematically:

• Does it stay in scope? Ask it to review a Python file. It should decline. Ask it to comment on variable naming. It should decline.
• Is the output format consistent? Review 3-4 different files. Every finding should follow the same structure.
• Does memory work? Ask it to review two files in the same session. On the second file, it should remember the tsconfig and project patterns from the first.
• Does it handle clean code? Review a well-typed file. It should say so clearly, not invent problems.
• Does it cap findings? Review a file with many issues. It should stop at 10 and note the remainder.

Iterate on AGENT.md until the output is what you would want from a colleague reviewing your types.

Step 5 — Publish

$ myclaude publish

Validating vault.yaml... OK
Scanning content... OK
Uploading files... OK
Creating listing... OK

Published: myclaude.sh/p/your-username-typescript-reviewer

Buyers install with:

$ myclaude install @your-username/typescript-reviewer

AGENT.md anatomy

Every AGENT.md should have these sections. Skip none of them.

Identity

Who is this agent? Write 2-4 sentences that establish:

• Domain expertise (what the agent knows deeply)
• Communication style (direct? educational? formal?)
• Opinions (what does the agent believe about its domain?)

Identity is not flavor text. It shapes Claude's behavior on every response. A "senior security engineer who believes in defense in depth" produces different output than a "security consultant who prioritizes pragmatism over completeness." Choose the identity that produces the output your buyers need.

Capabilities

What does the agent do? List the specific areas of expertise. Be exhaustive but not infinite — if the list exceeds 20 items, the agent's scope is too broad. A focused agent with 5-10 capabilities outperforms a broad one with 30.

Group capabilities by sub-domain. In the TypeScript reviewer example: type safety, strict mode compliance, common pitfalls. This grouping helps Claude prioritize and helps buyers understand what they are getting.

Constraints

What does the agent NOT do? This section is the difference between a predictable agent and an unpredictable one.

Every constraint should be concrete and testable. "Do not go off topic" is vague. "Only review .ts and .tsx files. Decline all other file types with the message: 'I review TypeScript files only.'" is testable.

Write constraints by imagining how a buyer might misuse the agent. They will ask your TypeScript reviewer to fix bugs, write new code, review CSS, explain React concepts. Each misuse case becomes a constraint.

Output format

What does the agent's output look like? Specify the exact structure. Include severity levels, field names, and formatting. Show the format for both "findings exist" and "no findings" cases.

Consistent output format is the primary reason buyers choose an agent over asking Claude directly. If your agent produces different formats on different invocations, the value proposition collapses.

Memory

What does the agent remember across interactions? This is what distinguishes an agent from a skill.

Common memory items:

• Configuration state (tsconfig, eslint config, project settings)
• Project patterns (naming conventions, library choices, architectural decisions)
• Previous findings (avoid redundant flagging across files)
• User preferences (if the buyer says "we allow any in test files," remember that)

Keep memory items specific and bounded. "Remember everything about the project" is not useful. "Remember the tsconfig compiler options and the project's validation library choice" is.

Examples

Show 2-4 examples of the agent in action. Cover:

• A typical case (the most common thing the agent will encounter)
• An edge case (something tricky that demonstrates the agent's depth)
• A clean case (input that requires no findings — show the agent says so)

Examples calibrate Claude's behavior more than any amount of written instruction. If you spend extra time on one section, spend it here.

Best practices

Narrow scope beats broad scope. A "TypeScript strict mode reviewer" is more valuable than a "code quality agent." Buyers choose agents because they want specific expertise, not general capability — they already have Claude for that.

Test the constraints first. Before testing what the agent does right, test what it refuses to do. Send it off-topic requests. Ask it to do things outside its domain. If it complies, tighten the constraints.

Write the output format before writing the instructions. Start from what the buyer should see, then work backwards to the instructions that produce it. This prevents the common failure mode of detailed instructions that produce unstructured output.

Use the references directory. For agents priced above $0, add a references/ directory with domain knowledge. A TypeScript reviewer with a references/common-pitfalls.md file containing 50 real-world TypeScript type errors (with explanations and fixes) is dramatically more useful than one relying solely on Claude's general knowledge.

Memory should be bounded. An agent that tries to remember everything becomes unpredictable. Define exactly what it tracks, how long it persists (within session vs. across sessions), and when it resets.

Related pages

• Writing Skills Guide — if your agent would be simpler as a stateless skill, start there
• Building Squads — combine multiple agents into a coordinated team
• vault.yaml Specification — agent-specific vault.yaml fields
• MCS Certification — agent MCS requirements by tier
• Publishing Your First Product — the basics of publishing any product type