Atomic VCS canonical skills and workflow instructions.
This is the single source of truth for the Atomic agent workflow body (AGENTS.md) and the on-demand skills every Atomic-aware agent loads. It is consumed by all 12 agent integration packages (atomic-opencode, atomic-claude, atomic-codex, etc.) via [skills-source] in their atomic-integration.toml manifests.
Definitive source: this repository lives on Atomic storage. The GitHub repo is a mirror. The CLI clones it into
~/.atomic/integrations/atomic-skills/repo(shared cache) on everyatomic agent enable.
atomic-skills/
├── AGENTS.md # vendor-neutral workflow body
├── atomic-integration.toml # declares the skills (below)
└── skills/
├── atomic-vault/SKILL.md # intent lifecycle, vault commands, memory operations
├── atomic-vcs/SKILL.md # read-only VCS: status, log, change, diff
├── code-intelligence/SKILL.md # knowledge graph + content search (replaces grep)
├── intent-builder/SKILL.md # how to author structured intents
├── decision-record/SKILL.md # capture durable insights as attestable memories
└── triage-review/SKILL.md # review change-sets before cross-view promotion
The canonical, vendor-neutral agent workflow body. It establishes:
- "You use Atomic VCS, not git." — the agent uses Atomic CLI commands instead of git.
- The intent-first workflow. — every unit of work becomes a directive-based intent (
:::why,:::acceptance-criterion,:::task) that must validate and attest. - "Do NOT run
atomic addoratomic record." — hooks record automatically with provenance. - Point at the skills. —
atomic-vault,atomic-vcs,code-intelligence, etc.
Each plugin delivers this body to the agent through one of two paths:
- Bundled agent (OpenCode, Claude, Kilo, Pi): The plugin ships a frontmatter template (
agents/atomic.md.frontmatter). At install time, the CLI stitches the frontmatter + thisAGENTS.mdbody together via[agent-definition]in the plugin manifest. The user picks the "Atomic" agent in their IDE. - Repo-level AGENTS.md (all agents):
atomic agent enable --agents-mdcopies thisAGENTS.mdinto the repo root. Every agent in that repo gets the workflow automatically — no agent picking. If the repo already has anAGENTS.md, the installer appends the canonical content with a---separator, preserving the user's project-specific content.
Skills are on-demand reference documents the agent loads when a task calls for them (kept out of the always-on prompt to save context). Every Atomic agent pulls the same skills from this package so that behavior is identical no matter which agent the user runs.
| Skill | Description |
|---|---|
atomic-vault |
Intent lifecycle, vault CLI commands, memory operations |
atomic-vcs |
Read-only VCS inspection: status, log, change -p, diff |
code-intelligence |
Knowledge graph + content search (replaces grep/find) |
intent-builder |
How to author structured, conforming intents |
decision-record |
Capture durable insights as attestable memories at turn end |
triage-review |
Review change-sets before cross-view promotion |
The atomic-integration.toml in this package explicitly declares each skill via [[declared-skill]] entries:
[[declared-skill]]
name = "atomic-vault"
[[declared-skill]]
name = "triage-review"When a plugin's manifest has a [skills] block with install = "all", the installer:
- Clones this package into the shared cache (
~/.atomic/integrations/atomic-skills/repo) — always, on everyatomic agent enable, so new skills are picked up immediately. - Reads this manifest to get the declared skill list.
- For each declared skill, copies
skills/{name}/SKILL.mdto the plugin'sdst_pattern(formatted with{name}).
The CLI reads the manifest — it never scans the filesystem.
- Create
skills/<skill-name>/SKILL.mdwith the skill content and YAML frontmatter includingmetadata.version(a semantic version string) andmetadata.updatedAt(a quoted ISO 8601 timestamp with a timezone). - Add one
[[declared-skill]]entry toatomic-integration.toml:[[declared-skill]] name = "<skill-name>"
- Commit and push.
That's it. Every plugin that has [skills] install = "all" will pick up the new skill automatically on next atomic agent enable. Zero plugin manifest changes.
Edit the SKILL.md file, increment metadata.version, and set metadata.updatedAt to a later timestamp. Commit and push. Every plugin gets the update on next install — the CLI always re-clones the cache to get latest.
The Validate skill metadata pull request check runs skills-ref validate on every skill directory to check frontmatter and naming. It also enforces the version and timestamp fields on added and changed skills, comparing existing skills against the PR's base branch. The first metadata addition to a legacy skill without metadata is allowed; subsequent updates must increase both values. Deleted skills are ignored by the metadata comparison, and recognized renames are compared against the previous path. The upstream skills-ref library is a reference implementation intended for demonstration, not production; it does not guarantee that skill instructions work correctly.
To enforce the check before merging, configure it as a required status check in the repository's branch protection or ruleset. Require branches to be up to date before merging to ensure the check uses the latest base metadata, and require review of changes to the workflow and validator to prevent the check from being bypassed. For local format checks, install skills-ref as described in its upstream documentation and run skills-ref validate skills/<skill-name>; the workflow pins the upstream revision.
Edit AGENTS.md, commit, push. The canonical body flows to:
- Bundled-agent plugins: stitched into the agent file at install time (frontmatter + body).
- Repo-level installs: copied/merged into the repo's
AGENTS.mdvia--agents-md.
No plugin repo changes needed.
A plugin's atomic-integration.toml declares:
[skills-source]
package = "atomic-skills"
[skills]
install = "all"
dst_pattern = "~/.config/opencode/skills/{name}/SKILL.md"
[[repo-file]]
src = "AGENTS.md"
dst = "AGENTS.md"
# For bundled-agent plugins only:
[agent-definition]
src = "agents/atomic.md.frontmatter"
body_from = "atomic-skills:AGENTS.md"
slot = "~/.config/opencode/agents/atomic.md"[skills-source]— names this package as the shared cache.[skills]—install = "all"reads the declared skills from this package's manifest;dst_patternformats the per-vendor destination path with{name}.[[repo-file]]— installsAGENTS.mdinto the repo root (when the user opts in via--agents-md).[agent-definition]— stitches the plugin's frontmatter + this package'sAGENTS.mdbody into the vendor's agent slot.
Vendors with flat skill layouts (Cline: Workflows/{name}.md, agy: plugin/skills/{name}.md) use a flat .md filename in dst_pattern instead of {name}/SKILL.md.
See the Adding a New AI Agent to Atomic guide in the atomic repo for the full walkthrough: hook adapters, manifest fields, plugins vs hooks manifests, the test harness, and the checklist.
Dual-licensed under MIT and Apache 2.0.