docs: add skills.md

AGENTS.md

@@ -20,4 +20,4 @@ This is a **PaperMC/Spigot Minecraft plugin template**. The intent is that users
 - `main.yml` — builds, tests, and cuts a snapshot release on push to `main`
 - `tag.yml` / `release.yml` — handle tagged releases and Discord notifications
 
-**Agent files (skills + `CLAUDE.md`)**: Two Claude-Code-facing outputs are generated from tracked sources and gitignored. (1) Canonical skills live in `.agents/skills/` (shared with other agents); `.claude/skills/` is a **generated mirror** — Claude Code only discovers skills there. **Edit skills only in `.agents/skills/`; never edit the mirror.** (2) `CLAUDE.md` is a **generated copy of this `AGENTS.md`** — `AGENTS.md` is the single source of truth for project instructions; **edit `AGENTS.md`, never `CLAUDE.md`.** `.claude/hooks/sync-agent-files.sh` regenerates both; `.claude/settings.json` runs it on `SessionStart` (with `reloadSkills` so new skills load in-session) and on `PostToolUse` after edits under `.agents/skills/**` or to `AGENTS.md`. Run `sh .claude/hooks/sync-agent-files.sh` to regenerate manually.
+**Agent instructions**: (1) Canonical skills live in `.agents/skills/`; `.claude/skills/` is a generated mirror. (2) `CLAUDE.md` is a generated copy of this `AGENTS.md`. (3) No agents are permitted to edit or create `CLAUDE.md` or `.claude/skills/`; Claude hooks established in `.claude/settings.json` automatically sync these mirrors on `SessionStart` and `PostToolUse`.

README.md

@@ -49,6 +49,7 @@ In order to use this template for yourself, there are a few things that you will
 - [Extending the example code](docs/usage.md) — add commands, subcommands, config fields, or persistent per-player data
 - [Customizing this template](docs/customization.md) — the one-time checklist for forking this repo (placeholders, secrets, etc.)
 - [Releases & versioning](docs/releases.md) — PaperMC compatibility, version format, and how to cut a release
+- [Agent instructions & skills](docs/skills.md) — agent guidance, Claude Code support, and available skills
 
 ## Building locally
 Thanks to [Gradle](https://gradle.org/), building locally is easy no matter what platform you're on. Simply run the following command:

docs/skills.md

@@ -0,0 +1,44 @@
+# Agent instructions and skills
+
+This repository keeps agent instructions in the AGENTS standard.
+Contributors should only edit these standard files.
+
+## Sources of truth
+
+- `AGENTS.md` contains repository-wide context and constraints, including the
+  plugin architecture, packaging, dependencies, command registration, versioning, and CI setup.
+  Agents will read this file automatically at the beginning of a session.
+- `.agents/skills/` contains reusable, task-specific instructions. Each
+  skill lives in its own directory and is defined by a `SKILL.md` file.
+  Agents get a list of available skills and can decide when to read their full contents.
+
+#### Claude Code sync
+
+`.claude/hooks/sync-agent-files.sh` copies the following:
+
+| Canonical, tracked source | Generated, ignored Claude Code file |
+| --- | --- |
+| `AGENTS.md` | `CLAUDE.md` |
+| `.agents/skills/<skill>/` | `.claude/skills/<skill>/` |
+
+Hooks in `.claude/settings.json` run synchronization automatically:
+
+- `SessionStart` on new, resumed, and cleared sessions.
+- `PostToolUse` when Claude Code writes or edits AGENTS sources.
+
+Do not edit or create `CLAUDE.md` or files under `.claude/skills/`.
+They are automatically generated/replaced by scripts, and never tracked.
+
+## Adding a skill
+
+1. Create `.agents/skills/<skill-name>/SKILL.md`.
+2. Write the following:
+
+```
+---
+name: skill-name
+description: Give it a short description.
+---
+```
+
+`name` is the same as the directory.