.agents/: add skills for working on this repo

Five skills covering this repo's own conventions: adding a bootstrap module, adding a CLI to bin/, bumping a pinned version, adding an MCP server, and verifying a module change. Lives in .agents/skills/ because opencode discovers that path natively alongside .opencode/skills/ and .claude/skills/, making it the most tool-neutral of the three. Distinct from the repo's skills/ tree, which ships to every covert-gpt user via sync.sh; these stay in the checkout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 13:10:18 -04:00
parent 6dc34c5dbb
commit 485e267565
6 changed files with 431 additions and 0 deletions
@@ -0,0 +1,76 @@
+# .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.