Skip to content
Back to search

agentops-marketplace

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 16 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/boshu2/agentops with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/boshu2/agentops'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/boshu2-agentops/badge.svg)](/listings/boshu2-agentops)

HTML

<a href="/listings/boshu2-agentops"><img src="/api/listings/boshu2-agentops/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pick one method per agent: a plugin plus npx on the same agent gives you every skill twice.

<details> <summary><strong>Claude Code</strong></summary>

<a id="claude-code"></a>

claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace
claude plugin details agentops@agentops-marketplace

Check that `agentops` appears in the plugin inventory. The bundle includes skills, four agents and [tool-call guards](#optional-admission-control-hooks).

</details>

<details> <summary><strong>Codex</strong></summary>

<a id="codex"></a>

codex plugin marketplace add boshu2/agentops
codex plugin add agentops@agentops-marketplace
codex plugin list --json

Check that `agentops` appears in the inventory. Skills use the `agentops:` prefix; custom roles and read limits have [separate setup](docs/install-day2-ops.md#install-and-update-runtime-plugins).

</details>

<details> <summary><strong>Everything else</strong> (Cursor, OpenCode, Gemini CLI, Pi, OpenClaw, Grok Bot)</summary>

<a id="everything-else"></a>

With Node.js installed, run from your project directory, then pick your agents and skills:

npx skills@latest add boshu2/agentops

Add `-g` for a user-level install. In scripts, name the agents: `npx skills@latest add boshu2/agentops -g -a cursor opencode -y` (`-y` without `-a` can install into every agent the installer knows). Installer targets include `cursor`, `opencode`, `gemini-cli`, `antigravity`, `pi`, `grok` (Grok Build) and `openclaw`. Grok Bot has no installer target; add the same `SKILL.md` folders through [its skill settings](https://docs.x.ai/grok-bot/skills-routines-and-automations). Some skills need extra tools ([install guide](docs/install-day2-ops.md)); what each host has been tested for is in [host coverage and limits](docs/contracts/multi-runtime-tier-charter.md#host-and-install-surface-mapping).

</details>

Start a new session so the skills load. Most skills need only your coding agent; a few use the [`ao` CLI](#optional-ao-cli) when it is installed. Invocation names vary by agent: this README shows Claude Code's `/agentops:<skill>`; Codex uses `$agentops:<skill>`.

<a id="workflow"></a>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines
  1. {
  2. "name": "agentops-marketplace",
  3. "owner": {
  4. "name": "Boden Fuller",
  5. "email": "fullerbt@users.noreply.github.com"
  6. },
  7. "metadata": {
  8. "description": "Engineering guidance for coding agents: behavior-driven planning, shared domain language, independent validation, and reusable improvements.",
  9. "version": "3.12.1"
  10. },
  11. "plugins": [
  12. {
  13. "name": "agentops",
  14. "description": "Engineering guidance for coding agents: behavior-driven planning, shared domain language, independent validation, and reusable improvements.",
  15. "version": "3.12.1",
  16. "source": "./plugin",
  17. "author": {
  18. "name": "Boden Fuller",
  19. "email": "fullerbt@users.noreply.github.com"
  20. }
  21. }
  22. ]
  23. }
README.md · README · 700 lines
  1. <div align="center">
  2. <img src="docs/assets/logo.svg" alt="AgentOps" width="72" height="72">
  3. # AgentOps
  4. **Software engineering practice, re-tested for AI agents.**
  5. [![Validate](https://github.com/boshu2/agentops/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/boshu2/agentops/actions/workflows/validate.yml)
  6. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  7. [![Latest release](https://img.shields.io/github/v/release/boshu2/agentops)](https://github.com/boshu2/agentops/releases/latest)
  8. [![Skills](https://img.shields.io/badge/skills-catalog-black.svg)](docs/SKILL-ROUTER.md)
  9. [Install](#quickstart) · [The loop](#the-operational-loop) ·
  10. [Goals](#goals) · [Try it](#try-it) · [Skills](#skills-at-a-glance) ·
  11. [Make it yours](#make-it-yours) · [Evidence](#evidence) ·
  12. [Beyond AgentOps](#beyond-agentops)
  13. </div>
  14. Fifty years of software engineering produced practices that work for human
  15. teams: state the behavior first, work in small slices, keep the checker separate
  16. from the author, isolate concurrent work. AgentOps runs those practices against
  17. AI coding agents and keeps the ones that hold up.
  18. You get three things:
  19. - **[Skills](docs/SKILL-ROUTER.md).** Each one is a Markdown file that carries
  20. one engineering practice into an agent session: [Plan](skills/plan/SKILL.md)
  21. to state the expected behavior, [Implement](skills/implement/SKILL.md) to
  22. change code without weakening its tests, [Validate](skills/validate/SKILL.md)
  23. for an independent judgment where a mistake would be costly.
  24. - **[The practice ledger](docs/practice-ledger.md).** It says which practices
  25. held, which changed shape, which did not survive, and which are still being
  26. tested, with the evidence for each.
  27. - **[Eval cases](evals/plugin-eval/README.md).** Run them on your own model
  28. before you trust a skill. Results change with the model and the harness.
  29. The skills are a kit, and you are expected to change it. Keep the ones that fit
  30. how you work, rewrite the ones that almost fit, delete the rest, and add skills
  31. you write yourself or find in other libraries. [Make it yours](#make-it-yours)
  32. shows how.
  33. Every measurement here was taken with Claude Code. The skills are plain
  34. Markdown and also install in Codex, Cursor, OpenCode, Gemini CLI and Pi, where
  35. they are untested. Start with [one useful task](#try-it); follow the
  36. [operational loop](#the-operational-loop) for a change or the
  37. [goal workflow](#goals) for work across sessions. The [`ao` CLI](#optional-ao-cli)
  38. and [Beads](https://github.com/gastownhall/beads) are optional.
  39. <a id="why-these-skills-exist"></a>
  40. ## Why use AgentOps?
  41. A [software factory](https://learn.microsoft.com/en-us/archive/msdn-magazine/2006/december/service-station-web-service-software-factory)
  42. makes engineering practices reusable through tools, guidance and repeatable
  43. workflows. AgentOps brings that approach into the coding session: clear intent,
  44. automated checks, recorded decisions and a feedback loop into later work. Pick
  45. the path your task needs and use the same practices when you change agents.
  46. [Behavior-driven development (BDD)](https://dannorth.net/introducing-bdd/)
  47. starts by agreeing on what the software should do in a concrete situation.
  48. For retries, that could mean: “If a completed job arrives again, return its
  49. result and charge the customer only once.” The same behavior guides the
  50. implementation, its tests and any review. [Plan](skills/plan/SKILL.md) helps you
  51. settle those expectations before the agent starts editing.
  52. | When you need to… | AgentOps adds |
  53. |---|---|
  54. | Decide what to do with an incoming report | [Triage](skills/triage/SKILL.md) reproduces a bug report, external PR or alert, checks for duplicates and earlier decisions, and recommends an outcome with the evidence behind it. Accepted work gets a brief an agent can act on without the original conversation. |
  55. | Get the agent to build what you meant | [Plan](skills/plan/SKILL.md) makes the expected behavior clear enough to implement and test. [Domain](skills/domain/SKILL.md) keeps the same names for concepts in the request, code and tests. |
  56. | Fix a design that makes every change expensive | [Architecture](skills/architecture/SKILL.md) finds where the structure makes change costly and compares at least two interface designs by the call sites they produce. [Refactor](skills/refactor/SKILL.md) then makes the chosen change without changing behavior. |
  57. | Build a tool that agents can use | [Ergonomics](skills/ergonomics/SKILL.md) checks whether an agent can find a CLI, API or MCP tool, read its output and recover from its errors, with the exact command and output behind each finding. |
  58. | Keep a project moving after the chat ends | [Interview](skills/interview/SKILL.md) settles a large goal with you. [Beads](https://github.com/gastownhall/beads) preserves its intent, decisions and results in a searchable work graph, with persistent project memories for later sessions. [Navigate](skills/navigate/SKILL.md) identifies ready work, blockers and gaps in the goal. |
  59. | Check whether the finished change meets the request | [Test](skills/test/SKILL.md) helps write checks for the intended behavior. Ordinary changes finish on checks and CI; [Validate](skills/validate/SKILL.md) adds one fresh review when requested, hard to undo, or uncovered by a deterministic check. |
  60. | Turn earlier work into useful context | [Research](skills/research/SKILL.md) traces the code and cites what it finds. [Memory](skills/memory/SKILL.md) can draw on Beads handoffs, Git changes and check results to explain a decision in a report, or curate supported lessons into reviewed project documents. Later agents can recall the lesson and follow its sources. |
  61. | Make a useful method repeatable | [Skill Builder](skills/skill-builder/SKILL.md) turns supported expertise into guidance with clear inputs, actions and limits. [Skill Eval](skills/skill-eval/SKILL.md) measures whether that guidance helps a named task, so it can be retained, revised or removed. |
  62. <a id="install"></a>
  63. ## Quickstart
  64. Pick one method per agent: a plugin plus npx on the same agent gives you every
  65. skill twice.
  66. <details>
  67. <summary><strong>Claude Code</strong></summary>
  68. <a id="claude-code"></a>
  69. ```bash
  70. claude plugin marketplace add boshu2/agentops
  71. claude plugin install agentops@agentops-marketplace
  72. claude plugin details agentops@agentops-marketplace
  73. ```
  74. Check that `agentops` appears in the plugin inventory. The bundle includes
  75. skills, four agents and [tool-call guards](#optional-admission-control-hooks).
  76. </details>
  77. <details>
  78. <summary><strong>Codex</strong></summary>
  79. <a id="codex"></a>
  80. ```bash
  81. codex plugin marketplace add boshu2/agentops
  82. codex plugin add agentops@agentops-marketplace
  83. codex plugin list --json
  84. ```
  85. Check that `agentops` appears in the inventory. Skills use the `agentops:` prefix;
  86. custom roles and read limits have [separate setup](docs/install-day2-ops.md#install-and-update-runtime-plugins).
  87. </details>
  88. <details>
  89. <summary><strong>Everything else</strong> (Cursor, OpenCode, Gemini CLI, Pi, OpenClaw, Grok Bot)</summary>
  90. <a id="everything-else"></a>
  91. With Node.js installed, run from your project directory, then pick your agents
  92. and skills:
  93. ```bash
  94. npx skills@latest add boshu2/agentops
  95. ```
  96. Add `-g` for a user-level install. In scripts, name the agents:
  97. `npx skills@latest add boshu2/agentops -g -a cursor opencode -y`
  98. (`-y` without `-a` can install into every agent the installer knows).
  99. Installer targets include `cursor`, `opencode`, `gemini-cli`, `antigravity`,
  100. `pi`, `grok` (Grok Build) and `openclaw`. Grok Bot has no installer target; add
  101. the same `SKILL.md` folders through [its skill settings](https://docs.x.ai/grok-bot/skills-routines-and-automations).
  102. Some skills need extra tools ([install guide](docs/install-day2-ops.md)); what
  103. each host has been tested for is in [host coverage and limits](docs/contracts/multi-runtime-tier-charter.md#host-and-install-surface-mapping).
  104. </details>
  105. Start a new session so the skills load. Most skills need only your coding
  106. agent; a few use the [`ao` CLI](#optional-ao-cli) when it is installed. Invocation names
  107. vary by agent: this README shows Claude Code's `/agentops:<skill>`; Codex uses
  108. `$agentops:<skill>`.
  109. <a id="workflow"></a>
  110. ## The operational loop
  111. Each change is shaped, built and checked. Use one fresh review when requested,
  112. when a mistake cannot be cheaply undone, or when no deterministic check covers
  113. the changed behavior. You (or Plan) write intent as
  114. behavior ([BDD](https://dannorth.net/introducing-bdd/)), using one word per
  115. concept ([DDD](https://martinfowler.com/bliki/DomainDrivenDesign.html)'s
  116. [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html)).
  117. For a system that calls queued work a **Job**, in [Gherkin](https://cucumber.io/docs/gherkin/reference/):
  118. ```gherkin
  119. Feature: Job redelivery is idempotent
  120. A Job is one unit of queued work. Delivering it again never repeats its side effect.
  121. Scenario: A completed Job is delivered again
  122. Given Job "J-42" completed and charged the customer $20
  123. When the worker receives Job "J-42" again
  124. Then it returns the completed result of "J-42"
  125. And the customer has been charged $20 exactly once
  126. Scenario: A Job that failed before charging is delivered again
  127. Given Job "J-43" failed before charging the customer $20
  128. When the worker receives Job "J-43" again
  129. Then Job "J-43" completes
  130. And the customer has been charged $20 exactly once
  131. ```
  132. The feature defines the domain term once; each scenario has concrete data, one
  133. action and an observable result. Keep scenarios in the issue or conversation;
  134. no `.feature` file is required.
  135. <p align="center">
  136. <img src="docs/assets/agentops-routes.svg" alt="Clear accepted intent goes straight to Implement; unclear intent goes to Plan first. Implement runs native checks and CI. Ordinary changes finish on those checks. Use one fresh author-distinct review when requested, when a mistake cannot be cheaply undone, or when no deterministic check covers the changed behavior. An existing change can enter at review. Repair findings within scope and confirm with affected checks; another review requires a caller request. NOT_PROVEN reports missing evidence without claiming PASS. The optional learning loop sends a result to a protected draft, fresh support and disclosure review, reviewed .context/ pages, and later work." width="100%">
  137. </p>
  138. | Step | Skill | What it does with the scenarios |
  139. |---|---|---|
  140. | Shape | [`plan`](skills/plan/SKILL.md) | Turns the request into scenarios for one small change. Skip it when intent is clear. |
  141. | Build | [`implement`](skills/implement/SKILL.md) | Makes the change and tests both scenarios. |
  142. | Judge when needed | [`validate`](skills/validate/SKILL.md) | A new session that didn't write it returns `PASS`, `FAIL` or `NOT_PROVEN` against the same scenarios. |
  143. | Learn | [`memory`](skills/memory/SKILL.md) | Optional: reviewed `.context/` pages that later work can query. |
  144. Enter at the step you need. An existing change can enter at Validate when an
  145. acceptance judgment is needed. Ordinary changes finish on checks and CI. Review
  146. is one round: repair findings and confirm with affected checks; review again only
  147. when you ask. Report `NOT_PROVEN` with its gaps. The author cannot issue its own
  148. `PASS`. Merging and releasing follow your repo's rules.
  149. <a id="goals-many-rpis-over-a-bead-graph"></a>
  150. ## Goals
  151. [`rpi`](skills/rpi/SKILL.md) runs Plan → Implement → checks, with Validate where a
  152. mistake is costly, for one outcome
  153. without check-ins (your agent's permission prompts still apply) and stops at
  154. acceptance, a blocker or a spent limit. Bigger work becomes a goal (it
  155. needs Beads: `brew install beads`, then `bd init` in your repo):
  156. 1. **[Interview](skills/interview/SKILL.md).** One question at a time, each with
  157. a recommended answer. You settle the outcome, its examples, domain terms,
  158. non-goals, authority and budget before agents go autonomous.
  159. 2. **[Craft Goal](skills/craft-goal/SKILL.md).** Returns `SAFE_TO_CREATE` plus a
  160. prompt to paste into `/goal` (Claude Code or Codex), `USE_PLAN` (one change:
  161. Plan or native execution), or `UNSAFE_GOAL` plus what's undecided. It creates
  162. nothing itself.
  163. 3. **[Navigate](skills/navigate/SKILL.md) each round.** Picks a few ready work
  164. items (beads); each gets one RPI, checks and CI, with one fresh Validate
  165. when requested, hard to undo, or uncovered by a deterministic check. The goal ends
  166. `ACHIEVED`, `NOT_ACHIEVED` or `NEEDS_OPERATOR`.
  167. <p align="center">
  168. <img src="docs/assets/agentops-goal-graph.svg" alt="A goal observes the Beads work graph, picks ready beads, consumes checks and any verdicts, then ratchets or stops. Each bead gets one RPI: Plan when unclear, Implement, and checks. When delegation is authorized, each fresh worker starts with one bead. Validate runs in a separate fresh context only when requested, when a mistake is hard to undo, or when no deterministic check covers the change. Results and notes return to the bead." width="100%">
  169. </p>
  170. **Beads remembers the work.** [Beads](https://github.com/gastownhall/beads) (`bd`)
  171. keeps the goal and its history outside any conversation. The root epic holds
  172. acceptance; child beads carry the scoped work, design decisions, handoffs and
  173. result notes. Record which checks ran and link any review evidence to the same
  174. bead. That connects the original intent to the checked output, so the next
  175. session can continue from the record instead of reconstructing the chat.
  176. `bd ready` finds unblocked work; search and history help explain earlier choices.
  177. Beads also has a [persistent memory store](https://github.com/gastownhall/beads/blob/main/docs/cli-reference/remember.md).
  178. `bd remember` saves project facts, `bd memories` searches them, `bd recall`
  179. retrieves one by key, and `bd prime` brings stored memories into session context.
  180. The work graph and the memory store serve different needs: one preserves what
  181. happened; the other keeps selected facts easy to find again.
  182. [Memory](skills/memory/SKILL.md) helps you use that material: recall relevant
  183. context, examine recorded decisions and outcomes, or draft a report with links
  184. to its evidence. When you want a reusable project document, it curates supported
  185. findings into reviewed `.context/` pages or an external document bundle. Beads
  186. keeps the work record; Git and the original evidence locations keep the code and
  187. check artifacts. Reusable documents link back to those sources.
  188. ```bash
  189. bd search "redelivery" --status all # include finished work
  190. bd show <bead-id> # intent, notes and relationships
  191. bd history <bead-id> # how the record changed
  192. bd remember "Redelivery returns the stored Job result" --key job-redelivery
  193. bd recall job-redelivery # retrieve the saved project fact
  194. ```
  195. **One bead per worker.** When the goal delegates, the orchestrator holds the
  196. graph and results, and each worker starts with one bead instead of the
  197. orchestrator's transcript. Reviewers, when needed, start fresh.
  198. ```bash
  199. bd create "Job redelivery is idempotent" -t epic
  200. bd create "Return the completed result on redelivery" --parent <epic-id>
  201. bd dep add <later-id> <earlier-id> # real ordering only
  202. bd ready --parent <epic-id> # the frontier
  203. ```
  204. Navigate shows `bd` commands; another tracker with status, dependencies and
  205. notes works if you map them. AgentOps never builds a second work index.
  206. ## Try it
  207. Start read-only in any repo, then swap the Job example for your own change.
  208. ```text
  209. # First look (changes nothing)
  210. /agentops:research how does this repo validate input? cite files and lines, change nothing
  211. # One change
  212. /agentops:plan make Job redelivery return the completed result without repeating the side effect
  213. /agentops:implement
  214. /agentops:validate # when requested, hard to undo, or uncovered by checks; use a new session
  215. # One outcome, end to end
  216. /agentops:rpi make Job redelivery return the completed result without repeating the side effect
  217. # A goal
  218. /agentops:interview make the job worker safe under redelivery, retries and crash recovery
  219. /agentops:craft-goal # then paste its prompt into /goal
  220. ```
  221. <a id="how-independent-review-works"></a>
  222. <details>
  223. <summary><strong>Validate an existing change</strong></summary>
  224. Pick a finished change whose accepted behavior is recorded in an issue or
  225. conversation. Run the required checks and keep the candidate unchanged.
  226. [Installing `ao`](#optional-ao-cli) is optional; it gives Validate a content
  227. manifest for the change. Then open a **new conversation**, fill in the
  228. references and paste:
  229. ```text
  230. Use the AgentOps Validate skill to judge this finished change.
  231. Original accepted behavior: [issue link or original request text]
  232. Candidate: [commit, branch or working tree; list every changed path]
  233. Author context ID: [task/session ID that made the change]
  234. Checks run: [commands and results]
  235. I opened this new conversation for fresh review. Derive the exact subject
  236. identity at the start and end, inspect every changed path against the original
  237. behavior, and do not modify the candidate. Report PASS, FAIL or NOT_PROVEN with
  238. evidence for each criterion, checked, not_checked, author and reviewer context
  239. IDs, and freshness attestation.
  240. ```
  241. `PASS` needs evidence for every criterion and an empty `not_checked`. `FAIL`
  242. names failed behavior or an out-of-scope change. Missing proof, identity or
  243. path coverage is `NOT_PROVEN`.
  244. </details>
  245. <a id="try-one-task"></a>
  246. <details>
  247. <summary><strong>Read-only skill-loading smoke test</strong></summary>
  248. Paste this in an agent conversation in your project. It needs no `ao` CLI.
  249. ```text
  250. Use the AgentOps Research skill to trace how this repository validates user
  251. input. Follow one path from the input through its checks and tests. Cite the
  252. files and line numbers, explain one edge case, and identify missing coverage.
  253. Name the Research skill file you loaded. Answer here without changing files.
  254. ```
  255. The reported skill path catches missing or duplicate installs. Invoke Research
  256. directly with `/agentops:research` in Claude Code, `$agentops:research` in
  257. Codex, or `/` and the installed Research entry in Cursor.
  258. </details>
  259. <a id="choose-skills-by-the-work"></a>
  260. ## Skills at a glance
  261. All skills are optional. Load one when it answers a specific question. Full
  262. catalog: **[docs/SKILL-ROUTER.md](docs/SKILL-ROUTER.md)**.
  263. | Group | Skills | What it covers |
  264. |---|---|---|
  265. | Operational loop | [`plan`](skills/plan/SKILL.md) [`implement`](skills/implement/SKILL.md) [`validate`](skills/validate/SKILL.md) | Shape and build a change; judge it where a mistake is costly |
  266. | Autonomous | [`rpi`](skills/rpi/SKILL.md) | One outcome, end to end |
  267. | Goals | [`interview`](skills/interview/SKILL.md) [`craft-goal`](skills/craft-goal/SKILL.md) [`navigate`](skills/navigate/SKILL.md) | Shape, write and walk a goal over the bead graph |
  268. | Coordination | [`orchestrate`](skills/orchestrate/SKILL.md) | Fresh workers per bead, disjoint scopes, integration |
  269. | On demand | [`research`](skills/research/SKILL.md) [`domain`](skills/domain/SKILL.md) [`test`](skills/test/SKILL.md) [`refactor`](skills/refactor/SKILL.md) [`review`](skills/review/SKILL.md) [`security`](skills/security/SKILL.md) [`doc`](skills/doc/SKILL.md) [`triage`](skills/triage/SKILL.md) [`architecture`](skills/architecture/SKILL.md) [`ergonomics`](skills/ergonomics/SKILL.md) | Reached for when a specific question comes up |
  270. | Learning | [`memory`](skills/memory/SKILL.md) | Curated `.context/` pages safe to commit |
  271. | Judgment strategies | [`council`](skills/council/SKILL.md) [`premortem`](skills/premortem/SKILL.md) [`postmortem`](skills/postmortem/SKILL.md) [`idea-genie`](skills/idea-genie/SKILL.md) | Multi-model councils (debates, idea duels, interview panels), idea brainstorms, plan challenges and postmortems |
  272. | Runtimes and factories | [`codex-exec`](skills/codex-exec/SKILL.md) [`claude-exec`](skills/claude-exec/SKILL.md) [`agy-native`](skills/agy-native/SKILL.md) | Selected executors |
  273. | Skill craft | [`skill-builder`](skills/skill-builder/SKILL.md) [`skill-eval`](skills/skill-eval/SKILL.md) | Author skills and measure whether they help |
  274. ## Make it yours
  275. Every skill here is a folder with one `SKILL.md`: plain instructions an agent
  276. loads when a task calls for them. No skill depends on the full set, and coding
  277. with none of them still works. That makes the library easy to take apart, and
  278. you should. The 28 skills are a starting point for an operating model that fits
  279. your work.
  280. - **Start small.** Install two or three skills that match work you already do.
  281. Add another when a real task asks for it.
  282. - **Cut what you override.** If you or the agent keep ignoring a rule, change
  283. the rule or remove the skill. `npx skills` lets you pick skills per agent, and
  284. [`ao skills link --skill <name>`](docs/install-day2-ops.md#install-source-checkout)
  285. links an exact subset from a checkout.
  286. - **Rewrite what almost fits.** Fork this repository, edit the `SKILL.md` and
  287. install from your fork with the same commands, or link a checkout so every
  288. agent on your machine reads your edits. A plugin update replaces the installed
  289. copy, so keep your changes in a repository you control.
  290. - **Write your own.** When you have explained the same thing to an agent three
  291. times, it is a skill. [Skill Builder](skills/skill-builder/SKILL.md) drafts the
  292. package, and tells you when a note in an existing file is enough.
  293. - **Mix libraries.** Run these next to your company's skills, the
  294. [Agentic Coding Flywheel](#agentic-coding-flywheel) tools or any other
  295. library. `ao skills link` never replaces a skill it did not install.
  296. - **Change the workflows too.** The [operational loop](#the-operational-loop)
  297. and the [goal workflow](#goals) are defaults. Skip the steps your work does
  298. not need, reorder them, or write your own.
  299. - **Measure what you change.** `claude plugin eval` compares an agent with and
  300. without a plugin on the same request. To measure one edit, run the old and
  301. the new version as two plugins. [Skill Eval](skills/skill-eval/SKILL.md)
  302. covers how to read the result, and [Evidence](#evidence) shows the cases this
  303. repository runs; copy them for your own skills.
  304. ## Evidence
  305. A skill is a page of instructions, so the test is whether an agent does anything
  306. differently with it installed. AgentOps runs that test on Claude Code's own
  307. evaluator, `claude plugin eval`: one realistic request per skill, graded against
  308. four or five criteria taken from the practice the skill teaches. For Test, one
  309. criterion is that a regression test is shown failing without the fix.
  310. On Claude Opus 5.5, measured 2026-11-11 on version 3.12.0, three runs per
  311. request. "By name" is the same request with the skill named, so its rules are
  312. in play whether or not the agent would have loaded it:
  313. | | No plugin | AgentOps 3.12, request as typed | AgentOps 3.12, skill named |
  314. |---|---:|---:|---:|
  315. | Practice criteria met on 42 requests | 372 of 573 (65%) | 511 of 573 (89%) | 551 of 573 (96%) |
  316. | On the 20 requests where the unaided agent meets 70% or less | 122 of 282 (43%) | 233 of 282 (83%) | 266 of 282 (94%) |
  317. | Matching skill loaded on its own request | | 65 of 114 runs | |
  318. Twenty-three of the 28 skills moved their cases by more than 0.15 when named.
  319. Architecture, Claude Exec, Memory, Craft Goal and Plan gained the most. On the
  320. other 22 requests the unaided agent already met more than 70% of the criteria.
  321. The same run found one regression in 3.12.0: a rewritten description stopped
  322. Orchestrate from loading, and Agy Native loaded less often with it. Version
  323. 3.12.1 replaces that line with one from a measured trial; Orchestrate then
  324. loaded on 22 of 30 runs against 6 of 30. No other skill fell more than 0.15
  325. below its 3.11 score under the same judge on one of those 20 requests,
  326. except Implement when named, which a same-day re-run did not reproduce.
  327. Read the limits before you quote these numbers:
  328. - One to four requests per skill, three runs per arm, one model. A difference
  329. under 0.15 is noise.
  330. - The criteria come from each skill's own rules. A pass shows the rule landed on
  331. that request. It says nothing about the outcome of a real task, and an earlier
  332. [coding pilot](PRODUCT.md#evidence-and-claim-limits) found no end-to-end
  333. difference.
  334. - Loading is the weak point. Doc, Navigate, Research, Review, Security and
  335. Validate did not load on their unnamed routing request, and one skill's
  336. description can change whether another loads. A
  337. [trial](docs/evals/2026-10-31-description-trial-opus-5-5.md) rewrote two
  338. descriptions, after which Triage loaded on 13 of 13 runs and Implement on 7
  339. of 13. Name the skill when you want its rules applied.
  340. The [full report](docs/evals/2026-11-11-recheck-opus-5-5.md) has every case, the
  341. rules fixed before the runs and what was rerun. The
  342. [2026-10-22 report](docs/evals/2026-10-22-plugin-eval-opus-5-5.md) is the record
  343. for 3.11. The cases live in
  344. [`evals/plugin-eval/`](evals/plugin-eval/README.md): run them against your own
  345. changes, or copy the layout to test your own skills.
  346. ## Where AgentOps fits
  347. AgentOps grew from applying DevOps experience and established engineering
  348. practice to agents. The [Practice Registry](PRACTICE-REGISTRY.md) records the
  349. lineage; [how it works](docs/how-it-works.md) covers responsibilities.
  350. <details>
  351. <summary>Compare libraries, trackers and agent factories</summary>
  352. | Project or tool | Role alongside AgentOps |
  353. |---|---|
  354. | [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) | A connected development workflow and reusable solution records |
  355. | [Matt Pocock's skills](https://github.com/mattpocock/skills) | Composable practices for intent, domain modeling, TDD and review |
  356. | [Beads](https://github.com/gastownhall/beads) or your existing tracker | Owns work status, dependencies and handoffs |
  357. | Factories such as [Gas City](https://github.com/gastownhall/gascity) | Own agent coordination and execution through their native control plane |
  358. Choose which workflow leads the task. Carry accepted behavior and evidence
  359. into checks, and into [independent judgment](skills/validate/SKILL.md) where a
  360. mistake would be costly. Shared practices are not
  361. proof that every combination has been tested.
  362. </details>
  363. <a id="optional-ao-cli"></a>
  364. ## `ao` CLI (optional)
  365. Most skills need only your coding agent. With `ao` installed, Validate binds
  366. the exact change it judges to a content manifest; without it, Validate names
  367. the commit and the changed paths.
  368. ```bash
  369. brew tap boshu2/agentops
  370. brew trust --tap boshu2/agentops
  371. brew install agentops
  372. ao version
  373. ```
  374. With Go installed: `go install github.com/boshu2/agentops/cli/cmd/ao@latest`.
  375. `ao init` is optional evidence setup; `ao config --show` inspects configuration;
  376. `ao gate check` runs this repository's own gates (mainly for contributors). See the [command reference](cli/docs/COMMANDS.md) and
  377. [installation guide](docs/install-day2-ops.md).
  378. ## Updating and advanced setup
  379. <details>
  380. <summary><strong>Upgrading to 3.12</strong></summary>
  381. <a id="upgrading-to-312"></a>
  382. <a id="upgrading-to-311"></a>
  383. <a id="upgrading-to-310"></a>
  384. <a id="upgrading-to-39"></a>
  385. <a id="upgrading-to-38"></a>
  386. <a id="upgrading-to-37"></a>
  387. Version 3.12.1 changes one line: Orchestrate's description, which in 3.12.0
  388. kept Orchestrate and Agy Native from loading. Read the
  389. [3.12.1 release notes](docs/releases/2026-11-11-v3.12.1-notes.md); from 3.12.0
  390. there is nothing to do beyond updating and starting a new session.
  391. Version 3.12 removes four skill names. [`orchestrate`](skills/orchestrate/SKILL.md)
  392. now does what `agent-native` did, [`research`](skills/research/SKILL.md) carries
  393. `reality-check` and the adoption rules from `reverse-engineer`, and `using-gc`
  394. is gone. The other 28 skills keep their names; 24 of them changed in an audit that was
  395. [measured afterward](docs/evals/2026-11-11-recheck-opus-5-5.md).
  396. Read the [3.12 release notes](docs/releases/2026-11-10-v3.12.0-notes.md). Use the
  397. [plugin update instructions](docs/install-day2-ops.md#install-and-update-runtime-plugins)
  398. or, for npx installs, `npx skills@latest update` ([update notes](docs/install-day2-ops.md#update)).
  399. For Homebrew: `brew update && brew upgrade agentops`. In a source checkout, run
  400. `git pull --ff-only`, then rerun `ao skills link` with the same `--skill` and
  401. `--dest` flags you used before; without them it links every skill into every
  402. installed runtime. Start a new session afterward. New installs do not remove
  403. obsolete copies, so delete the four old skill directories from your agent's skills folder if they are still there.
  404. **Upgrading from 3.8 or earlier:** version 3.9 removed ten bundled external tool
  405. skills, retired three delivery workflows, deleted the old curl installers and
  406. changed the Codex plugin to read `skills/` directly. Read the
  407. [3.9 release notes](https://github.com/boshu2/agentops/releases/tag/v3.9.0) first.
  408. **Upgrading from 3.6 or earlier:** read the [migration guide](docs/MIGRATION.md).
  409. Version 3.7 removed commands and skill names, including `learn`, `codebase-recon`
  410. and `swarm`; their current owners are `memory`, `research` and `orchestrate`.
  411. See the [3.7 release notes](https://github.com/boshu2/agentops/releases/tag/v3.7.0).
  412. </details>
  413. <details>
  414. <summary><strong>Skill dependencies</strong></summary>
  415. <a id="other-installation-paths"></a>
  416. Skill installation does not install tool dependencies:
  417. | Skill | Needs | Why |
  418. |---|---|---|
  419. | `rpi` | `ao`, conditional | delegates exact-subject checks to Validate; only persists `verdict.v2` when requested |
  420. | `plan` | `ao`, conditional | runs `ao provenance snapshot-intent` with an explicit evidence root when the intent source is not durable |
  421. | `implement` | `ao`, conditional | at an integration boundary whose changed paths affect bound evidence, runs `ao provenance evidence-orphans` |
  422. | `validate` | `ao`, optional | with `ao`, derives exact subject identity from a content manifest and uses `ao provenance store-verdict` when persistence is requested; without it, names the commit and changed paths |
  423. | `council` | `ao`, optional | with `ao`, `subject_digest` is the `canonical_manifest_digest` from `ao provenance manifest`; without it, a sha256 over the subject's repo-relative files or its text |
  424. | `research` | `ao`, conditional | inspect selected goal measurements with `ao goals` or evidence-store facts with `ao status` |
  425. | `doc` | `ao`, optional | a requested continuity handoff may use `ao session handoff`/`rehydrate` |
  426. | `skill-builder` | `ao` 3.9 or later outside a source checkout, Go inside one; `python3`, conditional | build, check, heal and audit run through `ao skills`; build (any mode) and heal's fix mode refuse with exit 2 outside an AgentOps source checkout (no `scripts/generate-skill-mesh.py`, as in a plugin install); build without `--init-only` and heal's fix mode run that script, and `audit.sh --legacy` needs PyYAML |
  427. | `memory` | `python3`, conditional | a selected toil investigation can use the repository helper `scripts/toil-mining/recent_human.py` on cleared Codex sources |
  428. | `security` | `python3`, conditional | the composable suite and offline redteam surfaces run `security_suite.py` when that scan type is selected |
  429. </details>
  430. <details>
  431. <summary><strong>Shared project context</strong></summary>
  432. <a id="shared-project-context"></a>
  433. [Memory](skills/memory/SKILL.md) can read reviewed `.context/` notes with ordinary
  434. filesystem tools; no `ao` or Beads is needed. See this repo's [context map](.context/README.md).
  435. Adding notes requires authorized sources and fresh review of factual support
  436. and disclosure before Git admission. Drafts and evidence stay inline in the
  437. reply or in storage outside Git that the caller names. These procedures do not
  438. enforce access permissions or prove
  439. that saved notes improve later work. See [Memory's storage rules](skills/memory/SKILL.md#access-storage-and-honest-limits).
  440. </details>
  441. <details>
  442. <summary><strong>Permissions, optional hooks, and removal</strong></summary>
  443. <a id="optional-admission-control-hooks"></a>
  444. The Claude Code plugin includes PreToolUse guards for private tracker data in
  445. commits, manual provenance-ledger edits and installed-skill overwrites. Installing
  446. only `ao` does not add hooks; other paths can opt in through the [native hook installer](scripts/install-policy-dispatch.sh).
  447. Read-budget guards, Codex roles and trusted Codex hooks have [separate setup](docs/install-day2-ops.md#install-and-update-runtime-plugins).
  448. Disable Claude's plugin with `/plugin disable agentops`. Remove it with
  449. `claude plugin uninstall agentops@agentops-marketplace`; for Codex, use
  450. `codex plugin remove agentops@agentops-marketplace`; for npx installs, use
  451. `npx skills@latest remove`.
  452. </details>
  453. <details>
  454. <summary><strong>Architecture and saved review evidence</strong></summary>
  455. AgentOps is the operations layer for agentic engineering. Its federated integration graph
  456. connects evidence while Git owns content, the tracker owns work and the coding
  457. runtime or selected factory owns execution. Your repository owns delivery.
  458. Native execution requires zero AgentOps skills. [RPI](skills/rpi/SKILL.md),
  459. [Gas City](https://github.com/gastownhall/gascity) and [Agentic Coding Flywheel](https://agent-flywheel.com)
  460. are optional; their completion reports do not replace required checks or judgment.
  461. On request, Validate can save `verdict.v2` with exact content, checked scope and
  462. evidence. New proof belongs in selected, protected storage outside Git;
  463. existing evidence is preserved.
  464. Read the [architecture](docs/ARCHITECTURE.md), [operating contract](docs/agent-workflow-reference.md)
  465. and [storage rules](docs/adr/ADR-0016-state-tiers.md).
  466. </details>
  467. ## Troubleshooting
  468. <details>
  469. <summary>Common problems and how to report one</summary>
  470. | Symptom | What to check |
  471. |---|---|
  472. | `plugin` is not recognized | Update your agent to a version with plugin support |
  473. | A skill is missing | Check its inventory or picker, then start a new session |
  474. | `ao` is not found | Install the CLI and check PATH; Go installs usually use `$(go env GOPATH)/bin` |
  475. | A skill needs another tool | Check its dependencies in the installation guide |
  476. | An old skill name fails | Check the [migration guide](docs/MIGRATION.md#skills) and stale copies |
  477. [Report a reproducible issue](https://github.com/boshu2/agentops/issues) with your
  478. runtime version, install method, command or prompt, and observed result.
  479. Share only evidence you are authorized to disclose.
  480. </details>
  481. ## Limits
  482. Skills guide agents; installation alone does not enforce their instructions.
  483. A green test suite or an agreeing model can still miss a defect. Missing proof
  484. stays `NOT_PROVEN`. Saving notes does not establish improved outcomes or
  485. automatic knowledge compounding. See [product evidence and limits](PRODUCT.md).
  486. ## FAQ
  487. <details>
  488. <summary>CLI, reviewer model and storage questions</summary>
  489. **Do I need the CLI, an orchestrator or several agents?**
  490. No. Start with one coding agent and a skill such as Research, Test or Refactor.
  491. Use checks and CI for ordinary changes. Obtain one fresh, author-distinct
  492. judgment when requested, hard to undo, or uncovered by a deterministic check. Validate works
  493. without `ao`; with it, the verdict is bound to a content manifest of the change.
  494. **Must the reviewer use another model provider?**
  495. No. The default is a fresh context from the author's model family. Cross-model
  496. review is an explicit choice; independence still matters.
  497. **Must durable work live in Git?**
  498. No. Keep source in Git, handoffs in your tracker and requested proof in protected
  499. external storage, following each owner's access and retention rules.
  500. </details>
  501. ## Beyond AgentOps
  502. Start with one agent and a paved path. When work needs several agents, a factory
  503. can add scheduling, coordination and runtime supervision. Install AgentOps
  504. skills into its agent runtimes to carry the same behavior, testing and review
  505. practices into each task. The factory runs the agents; your checks and any
  506. required independent judgment establish what the result proves.
  507. ### Gas City
  508. [Gas City](https://github.com/gastownhall/gascity), from the organization behind
  509. [Beads](https://github.com/gastownhall/beads), provides configurable building
  510. blocks for multi-agent software factories: runtime providers, work routing,
  511. workflow formulas, packs and supervision. AgentOps 3.12 no longer ships a Gas
  512. City adapter skill: operate a factory through its own coordinator and operator
  513. documentation. Workers inside it can still use AgentOps skills for
  514. implementation, tests and validation.
  515. ### Agentic Coding Flywheel
  516. [Agentic Coding Flywheel](https://agent-flywheel.com) is Jeffrey Emanuel's
  517. ([Dicklesworthstone](https://github.com/Dicklesworthstone)) ecosystem of tools
  518. and workflows for operating coding agents. Its
  519. [setup project](https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup)
  520. assembles a multi-agent development environment. You can also adopt individual
  521. tools alongside AgentOps:
  522. | Need | Upstream tool | How it fits |
  523. |---|---|---|
  524. | Block covered destructive shell operations | [Destructive Command Guard (`dcg`)](https://github.com/Dicklesworthstone/destructive_command_guard) | Checks commands before execution through its configured integration. Adds mechanical protection alongside agent guidance. |
  525. | Find an earlier investigation or solution | [Coding Agent Session Search (`cass`)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Indexes and searches agent session histories. Retrieve relevant episodes as evidence for Memory or a new investigation. |
  526. | Turn session evidence into reusable skills | [Meta Skill (`ms`)](https://github.com/Dicklesworthstone/meta_skill) | Can mine selected CASS sessions into skill candidates with source links. Review the guidance and test it on another task before relying on it. |
  527. For example, use CASS to find how a recurring migration failure was resolved.
  528. Use [Memory](skills/memory/SKILL.md) to examine the supported lesson and curate
  529. project context. If the method belongs in a repeatable path,
  530. [Skill Builder](skills/skill-builder/SKILL.md) can help package it and
  531. [Skill Eval](skills/skill-eval/SKILL.md) can measure whether it helps later work.
  532. This connects session history to guidance you can inspect and improve.
  533. Gas City, the Flywheel and these tools are independent projects. Install them
  534. and their skills from their authors. Follow their native workflows, integrations and distribution terms.
  535. ## Contributing
  536. Contributions are welcome: documentation fixes, reproducible bug reports,
  537. tests, CLI improvements and skills. Read the [contribution guide](docs/CONTRIBUTING.md);
  538. to work on skills from a checkout, link them with
  539. [`ao skills link`](docs/install-day2-ops.md#install-source-checkout).
  540. Licensed under [Apache-2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.