noconnorandClaude Opus 4.8
485e267565
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>
77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# .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.
|