# .agents — skills for working *on* this repo

Task-scoped instructions a coding agent loads on demand when changing this
repo: how to add a module, bump a pin, wire an MCP server, verify a change.

`.agents/skills/` is a real discovery path, not a local convention — opencode
searches it natively, alongside `.opencode/skills/` and `.claude/skills/`. That
makes it the most vendor-neutral of the three, which is why the skills live
here rather than under a tool-specific directory.

## Not to be confused with `skills/`

Two different things, easy to mix up:

| | `skills/` (repo root) | `.agents/skills/` |
|---|---|---|
| Audience | every covert-gpt **user** | whoever is **editing this repo** |
| Shipped? | yes — `mcp-config/sync.sh` deploys it to `~/.config/mcp-sync/skills` | no, stays in the checkout |
| Content | general-purpose skills for daily work | this repo's own conventions |

A skill about *how bootstrap modules are structured* belongs here. A skill
about *how to write a Terraform module* belongs in `skills/`.

## Layout

Per the [opencode skills spec](https://opencode.ai/docs/skills/): one folder
per skill, each containing a `SKILL.md`.

```
.agents/skills/
  add-bootstrap-module/SKILL.md
  add-cli-tool/SKILL.md
  add-mcp-server/SKILL.md
  bump-pinned-version/SKILL.md
  verify-module/SKILL.md
```

Frontmatter requires `name` and `description`:

- **`name`** — 1–64 chars, `^[a-z0-9]+(-[a-z0-9]+)*$`, and it **must match the
  folder name**. A mismatch is the usual reason a skill doesn't show up.
- **`description`** — 1–1024 chars. This is the only part the model sees when
  deciding whether to load the skill, so write it to say **when to use this**,
  not just what it is.

`license`, `compatibility`, and `metadata` are optional; unknown fields are
ignored. These skills set none of them — `compatibility: opencode` in
particular would undercut the point of using a neutral directory.

## Other agents

opencode needs no configuration. For Claude Code, point its conventional path
at the neutral one:

```sh
mkdir -p .claude && ln -sfn ../.agents/skills .claude/skills
```

Most other agents accept a skills directory; give them `.agents/skills`.
Failing that, the files are plain Markdown — `@`-mention one directly.

## Verifying

```sh
opencode debug skill      # lists every skill opencode sees, with its path
```

If one is missing, check the folder name against the frontmatter `name`.

## Always-on conventions

These skills deliberately do *not* restate the repo's baseline rules (POSIX
`sh`, `set -eu`, idempotent, no sudo outside the modules that declare it, no
secrets in-repo). Those apply to every change, so they belong in a root
`AGENTS.md` that is always in context — not in a skill that loads only
sometimes. Each skill assumes them and covers only what is specific to its task.