AGENTS.md

Canonical instructions for agents editing this repository.

Contract

Skills are small operational contracts, not essays and not snapshots of the author's machine.

Prefer this semantic shape when it fits:

1. Goal
2. Input
3. Output
4. Rules or workflow

Front matter must identify the skill. The description field is selection metadata, not prose: use 2–8 comma-separated keywords only. Keep the body concise, preferably about 80 lines or less. Move detail into references/, scripts, or repository docs.

Canonical source

Every durable skill lives once under skills/<name>/.

Do not create independently edited OpenCode, Claude, .agents, Agent Zero, or other runtime copies. Client layouts are deployment adapters derived from the canonical package. $HOME/skills is the canonical local checkout for this repository.

See docs/formats.md for adapter, validation, and import rules.

Portability

Before adding or editing a skill, scan for author-specific assumptions:

• lost-rob0t/* repositories;
• usernames, hostnames, absolute home paths, or machine names;
• private infrastructure or DNS;
• a particular dotfiles/configuration manager;
• MCP server names that only exist because of one personal config;
• commands whose dependencies are not declared.

Convert those assumptions into portable semantics:

• state the required capability, package, service, or protocol;
• document the minimum installation/configuration needed;
• discover the current user's real configuration source instead of assuming the author's;
• when authorized and tooling permits, edit that source declaratively and document what changed;
• keep an author-specific fast path only when it is explicitly scoped as compatibility, never as the universal default;
• use configurable paths, environment variables, runtime discovery, or user-provided values instead of hardcoded personal paths.

Do not expose private infrastructure while making a skill portable.

Imported corpora

Raw agent backups are never repository content.

Before importing a skill, remove target-specific operational state, credentials, tokens, private keys, client identifiers, personal identifiers, addresses, internal DNS, target hosts, scan output, session state, and collected evidence. Preserve reusable technique, tooling, sequencing, verification, scripts, references, and assets.

Never paste raw private values into issues, PRs, commit messages, documentation, or CI output. Discuss the category of removed information instead.

External attribution

An externally authored skill must never be presented as original work from this repository or its maintainer.

For every external import or adaptation:

• preserve the upstream project name and canonical source URL;
• identify the upstream author, organization, or contributor group when the source provides it;
• preserve and declare the upstream license;
• record the imported version, tag, or commit revision when practical;
• use metadata in SKILL.md for machine-readable provenance such as author, source, upstream-version, upstream-revision, and provenance: external-import;
• add a visible attribution note in the skill or a linked reference so a reader cannot reasonably mistake the work for an original skill from this repository;
• retain attribution when adapting, shortening, or wrapping the upstream work rather than deleting it because the local form changed.

If the upstream license or authorship is unclear, stop and resolve provenance before committing the import. Do not invent attribution.

Repository changes

For a new skill:

1. create skills/<name>/SKILL.md and any support files;
2. add it to the canonical skills catalog in flake.nix;
3. update .github/workflows/nix.yml so CI checks the exported name and package;
4. add or adjust a client adapter only when current client behavior requires it;
5. update README/docs only when the new behavior changes repository semantics or setup;
6. run the narrowest relevant validation, then the full required checks.

Existing lib.opencodeSkills and lib.opencodeSkillNames are compatibility aliases. They must reference the canonical catalog, not a second source tree.

Do not edit generated installed copies of skills as their durable source.

Dependencies

Declare only dependencies the skill actually needs. Prefer capabilities over personal implementation details.

Bad:

Use lost-rob0t/dotfiles and its prolog MCP config.

Better:

Requires a Prolog MCP server exposing the operations used below. Configure it in the user's agent runtime if absent.

If setup is non-trivial, keep the skill contract short and link to references/ or docs/.

Script-first execution

Use skills/<name>/scripts/ as the deterministic execution layer when a skill owns repeatable mechanics that should not be regenerated by an LLM.

Prefer a support script for:

• discovery or capability probes;
• scaffolding and canonical file creation;
• multi-step verification gates;
• adapter/bootstrap installation;
• deterministic formatting, conversion, or validation;
• lifecycle glue whose ordering, arguments, or failure handling matter.

Keep policy, choices, and interpretation in SKILL.md. Keep target-repository business logic in the target repository: if a maintained upstream CLI or script already owns an operation, call it instead of vendoring a second implementation here. Do not create a wrapper around a single stable upstream command unless the wrapper adds real validation, safety, atomicity, orchestration, or portability.

Support scripts must:

• use explicit argument vectors instead of constructing shell strings when practical;
• fail closed on ambiguity and existing state rather than guessing or overwriting;
• provide --dry-run for meaningful mutations when practical;
• keep credentials and secret values out of output;
• use minimal declared dependencies and prefer the standard library;
• expose useful exit status and --help behavior;
• have focused tests for non-trivial logic.

Top-level scripts/ is repository maintenance only. Skill behavior belongs with the owning canonical package so it survives deployment to Agent Zero, OpenCode, and other adapters.

Verification

Run the repository-authoritative manifest gate with bash scripts/validate-skills; its Agent Skills specification/reference-validator revision is pinned in docs/formats.md. Run bash scripts/validate-support-scripts for skill support-script syntax.

A change is complete when:

• every canonical skill passes bash scripts/validate-skills;
• every support script passes bash scripts/validate-support-scripts;
• the skill still performs the intended operation;
• its description is 2–8 comma-separated keywords with no prose;
• personal assumptions are scoped or removed;
• dependencies and configuration are explicit;
• links and paths resolve;
• the canonical flake catalog, compatibility aliases, adapters, and CI agree;
• required checks pass.