# `.claude/` — Claude Code surfaces

This directory holds [Claude Code](https://claude.ai/code) artifacts: skills, rules, and subagents. **Other AI tools** (Cursor, Copilot, Codex, Aider) should read [`AGENTS.md`](../AGENTS.md) instead — `.claude/` is Claude-Code-specific.

## Layout

```text
.claude/
├── agents/                            Subagents (invoked via @<name>)
│   └── slopsmith-reviewer.md          Plugin-aware code review
├── rules/                             Globs-scoped behaviour rules
│   └── plugin-author.md               Rules that fire when editing plugins/**
├── skills/                            Skills (description triggers auto-invocation)
│   ├── plugin-scaffold/SKILL.md       Generate a new plugin skeleton
│   ├── plugin-validate/SKILL.md       Validate a plugin.json against the schema
│   └── speckit-*/                     Spec-kit skills (auto-generated; don't edit)
├── settings.json                      Repo defaults (no hooks enabled by default)
└── README.md                          You are here
```

## Conventions

- **Spec-kit owns `skills/speckit-*`.** Don't edit those manually — they're regenerated by the spec-kit installer (`.specify/`).
- **Repo skills live alongside spec-kit skills** in `skills/`. New skills should have a kebab-case directory name and a `SKILL.md` with YAML frontmatter.
- **Hooks are off by default.** Hooks in `.claude/settings.json` run in every contributor's Claude Code session — enabling one imposes work on everyone. The settings file ships with `hooks: {}` and a commented example so anyone who wants to opt in can copy it locally.
- **Subagent invocation.** Use `@slopsmith-reviewer` to invoke a subagent explicitly. Plain auto-routing isn't currently configured.

## Adding a new skill

1. Create `.claude/skills/<kebab-name>/SKILL.md`.
2. YAML frontmatter must include `name` (must match directory) and `description` (must read like a sentence — Claude Code matches the description against user intent for auto-invocation).
3. Body: instructions Claude follows when the skill triggers. Keep it concrete and short — long skills bit-rot.

## Adding a new rule

1. Create `.claude/rules/<topic>.md`.
2. Frontmatter may include `globs:` (array of glob patterns scoping when the rule applies). Without `globs`, the rule loads for every session.
3. Body: terse, imperative guidance — "always do X", "never do Y", "if you see Z, …".

## Why so little here?

The maintainer's personal Claude Code rules (context-mode routing, RTK, `@git-worker`, etc.) deliberately do **not** live in this repo. Those are user-global concerns in `~/.claude/` — keeping them out of the repo keeps the shared surface lean and makes the repo equally useful to contributors using Cursor, Copilot, plain editors, etc.