agentry

# CLAUDE.md

This file is operating guidance for any AI assistant working on agentry's source. End users read `README.md`; you read this.

## What this repo is

agentry is a small configuration framework that lets developers author AI coding agents and skills once, then sync them to multiple harnesses (Claude Code, Cursor, Codex, and OpenCode). Source-of-truth content lives in top-level directories — `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, and `mcp/`. A sync script generates harness-specific copies in `.claude/`, `.cursor/`, `.codex/`, `.opencode/`, and the MCP config files (`.mcp.json`, `.cursor/mcp.json`, `opencode.json`). This repo is public-grade: changes ship to GitHub, so quality and consistency matter on every commit.

## Cardinal rule

> **Never edit `.claude/`, `.cursor/`, `.codex/`, `.opencode/`, `.mcp.json`, `opencode.json`, or any other generated harness output directly.** They are regenerated by `npm run sync` and your edits will be silently lost. The source of truth lives in `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, and `mcp/`. If you find yourself opening a generated file to change behavior, stop and find the source file instead.

## How to add or modify content

**Add an agent.** Create `agents/<name>.md` with frontmatter, then run `npm run sync`.

```markdown
---
name: code-reviewer
description: Reviews staged changes for correctness, security, and maintainability. Invoke before commit or when the user asks for a review.
tools: [Read, Grep, Glob, Bash]
model: sonnet
---

# Code reviewer

Body — the instructions the agent follows when invoked.
```

**Add a skill.** Create `skills/<name>/SKILL.md` with frontmatter, then run `npm run sync`.

```markdown
---
name: tdd-workflow
description: Test-first development with explicit red-green-refactor loops. Invoke when starting a new feature or fixing a bug with reproducible behavior.
---

# TDD workflow

Body — the steps the assistant follows when this skill is invoked.
```

**Add an MCP server.** Create `mcp/<name>.json` — the server definition as it appears inside a harness's `mcpServers` map — then run `npm run sync`. The filename is the server name; do not inline secrets (reference an env var the harness expands).

```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
```

**Modify an existing component.** Edit the source file under `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, or `mcp/`. Run `npm run sync`. Commit the source change and the regenerated harness files together in a single commit so the tree stays internally consistent.

## Discipline

- **No speculative content.** Add what solves a real problem you or the maintainer has had. "Might be useful" is not enough.
- **Match existing patterns.** Before adding a new agent or skill, read 2–3 existing ones and match their format, depth, and tone.
- **Quality over quantity.** Five excellent skills beats fifty mediocre ones. This is agentry's whole positioning.
- **Every component needs a sharp `description`.** It tells the harness when to invoke the component. Vague descriptions cause vague invocations — name the trigger condition explicitly.
- **When in doubt, smaller is better.** Easier to expand a tight skill than to prune a sprawling one.

## Working style

- Be direct. No filler, no empty affirmations.
- Push back when you disagree with the user. Lead with the disagreement.
- Show your reasoning for non-obvious choices.
- Read the file before editing it. Never assume contents from the filename.
- One logical change per commit.

## Definition of done

Before declaring any change complete:

- [ ] Source-of-truth file written or modified under `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, or `mcp/`.
- [ ] `npm run sync` ran clean with no errors.
- [ ] No manual edits to `.claude/`, `.cursor/`, or any other generated directory.
- [ ] New content matches the format and depth of existing peers in the same directory.
- [ ] Commit message follows conventional commits style: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.

More agent context in MANVENDRA-github/agentry

82 other files this repository gives its agents, the first 60 shown.