dotfiles/.agents

.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: 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:

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

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.