agy-staff
agy-staff: delegate work to Google's Antigravity CLI (agy) from Claude Code and Codex.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/keli-wen-agy-staff)HTML
<a href="/listings/keli-wen-agy-staff"><img src="/api/listings/keli-wen-agy-staff/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.
These steps run a script from the network that findsafeskills does not scan.
For humans
Step 1 — install the Antigravity CLI ([official docs](https://antigravity.google/docs/cli/install)), then verify with `agy --version`. Node.js is also required:
curl -fsSL https://antigravity.google/cli/install.sh | bash
Step 2 — install the plugin into your harness:
claude plugin marketplace add keli-wen/agy-staff claude plugin install agy@agy-staff
codex plugin marketplace add https://github.com/keli-wen/agy-staff codex plugin add agy@agy-staff
<details> <summary>Using DeepSeek Harness?</summary>
Install in the **DeepSeek Harness** desktop app (**Plugins** in the left sidebar → install from package spec `github:keli-wen/agy-staff`), or from the terminal:
dsh plugin --profile desktop add github:keli-wen/agy-staff
For a local checkout during development, run `dsh plugin --profile desktop add /absolute/path/to/agy-staff` (use `--profile web` if running the web profile). `pnpm`, Node.js, and an authenticated `agy` on `PATH` are required.
Once enabled, the plugin mounts the **`agy staff`** visual subagent right-sidebar, native Cordis tools (`agy_brain`, `agy_worker`, `agy_job`), and all eight `/agy-*` skills (`/agy-brain`, `/agy-lead`, `/agy-staffer`, `/agy-researcher`, `/agy-reviewer`, `/agy-implementer`, `/agy-ask`, `/agy-jobs`). Upgrade with `dsh plugin --profile desktop add 'github:keli-wen/agy-staff#<tag-or-commit>'`.
</details>
<details> <summary>Using Pi?</summary>
Install: `pi install git:github.com/keli-wen/agy-staff`. Skills are prefixed as `/skill:agy-<persona>` (e.g. `/skill:agy-ask reply with OK`), including `/skill:agy-lead`, `/skill:agy-brain`, and `/skill:agy-jobs` for job management. Update with `pi update --extension git:github.com/keli-wen/agy-staff`, then run `/reload`.
</details>
<details> <summary>Using OpenCode?</summary>
With OpenCode V1 (verified on 1.18.34), install the package through its native plugin manager:
opencode plugin 'agy-staff@git+https://github.com/keli-wen/agy-staff.git' --global
Restart OpenCode, then run `/agy-ask reply with OK`. The plugin automatically registers all eight `agy-*` skills and their native slash commands, including `/agy-lead`, `/agy-brain`, and `/agy-jobs`. No separate skills path or command wrappers are needed. Node.js and an authenticated `agy` are required, as above.
OpenCode caches the complete package spec. Restarting does not refresh an unchanged Git spec. To upgrade, choose a newer Git tag or commit and run `opencode plugin 'agy-staff@git+https://github.com/keli-wen/agy-staff.git#<tag-or-commit>' --global --force`, then restart. See [the reference](docs/REFERENCE.md#opencode) for config and local development. OpenCode V2 is not covered by this adapter.
</details>
Restart Claude Code or Codex afterwards. First run: `/agy:ask reply with OK` (Claude Code) or `$agy:ask reply with OK` (Codex). Ask is tool-free and needs no setup.
> [!IMPORTANT] > **There is no mandatory setup step.** `staffer`, `researcher`, `reviewer` and `implementer` run **unrestricted** by default: agy can inspect the repo, run commands, and edit files. agy-staff keeps that practical with prompts that adapt to the current repo state. For example, when `implementer` starts in a dirty workspace, the companion tells agy which files already had changes and reminds it not to overwrite or deliver unrelated user work. If the task asks for a commit, push, or PR, agy can do that delivery; otherwise it leaves a working-tree diff for review. These prompt instructions do not provide permission isolation.
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 · 16 lines
- {
- "name": "agy-staff",
- "owner": {
- "name": "Keli Wen",
- "url": "https://github.com/keli-wen"
- },
- "description": "agy-staff: delegate work to Google's Antigravity CLI (agy) from Claude Code and Codex.",
- "plugins": [
- {
- "name": "agy",
- "source": "./",
- "description": "Gemini 4 Carbon / Argon second brain (brain), host-led orchestration (lead), and five fast Gemini 4 Hydrogen personas (staffer, researcher, reviewer, implementer, ask) over agy, with a two-profile permission model and background jobs.",
- "tags": ["antigravity", "gemini", "neon", "carbon", "argon", "hydrogen", "delegation", "code-review"]
- }
- ]
- }
README.md · README · 229 lines · 1 finding marked
- <p align="center"><img src="assets/logo/gemini-agy.svg" width="440" alt="AGY-STAFF"></p>
- <p align="center"><a href="README.md">English</a> | <a href="README.zh-CN.md">Simplified Chinese</a></p>
- <p align="center">
- <a href="https://antigravity.google/product/antigravity-cli"><img src="assets/badges/powered-by-antigravity.svg" height="20" alt="powered by: Antigravity"></a><br>
- <img src="assets/badges/model-gemini-4-carbon.svg" height="20" alt="model: Gemini 4 Carbon"> <img src="assets/badges/model-gemini-4-argon.svg" height="20" alt="model: Gemini 4 Argon"> <img src="assets/badges/model-gemini-4-hydrogen.svg" height="20" alt="model: Gemini 4 Hydrogen"><br>
- <a href="https://claude.com/claude-code"><img src="assets/badges/claude-code-plugin.svg" height="20" alt="Claude Code plugin"></a> <a href="https://developers.openai.com/codex/"><img src="assets/badges/codex-plugin.svg" height="20" alt="Codex plugin"></a> <a href="LICENSE"><img src="assets/badges/license-mit.svg" height="20" alt="license: MIT"></a>
- </p>
- Hire Google's Antigravity CLI (`agy`) as a staffer for **Claude Code**, **OpenAI Codex**, **DeepSeek Harness**, **Pi**, and **OpenCode**.
- [](assets/design.svg)
- **[Bench](#-bench--harness--orchestration) · [Install](#install) · [Examples](#cujs) · [Core design](#core-design) · [Build your own](#build-one-for-another-cli) · [Upgrade](#upgrade)**
- ## What & Why
- agy-staff pairs your senior agents with `agy`, which ships <img src="assets/icons/carbon.svg" width="16" height="16" alt=""> **Gemini 4 Carbon**, <img src="assets/icons/argon.svg" width="16" height="16" alt=""> **Gemini 4 Argon**, and fast <img src="assets/icons/hydrogen.svg" width="16" height="16" alt=""> **Gemini 4 Hydrogen**. Two orchestration modes (`lead` and `brain`), five personas (`staffer`, `researcher`, `reviewer` for code **and** plans, `implementer`, `ask`), and a model-facing `jobs` skill. Claude Code uses `/agy:<skill>` and Codex uses `$agy:<skill>`.
- GPT-6.1-Sol is slow even with fast mode on; Claude Code is quicker, but Fable quota is too scarce to spend grinding through every survey and review. agy gives you both a **fast worker** and a **second brain**: **Hydrogen** handles quick second opinions, research, reviews, and scoped implementation off to the side, while **Carbon** and **Argon** are strong enough in design and world knowledge to pair with Astra or Fable as a peer orchestrator — proposing routes from a second model family while your host checks assumptions and delivers.
- 
- agy-staff gives you opinionated, task-named skills ready out of the box. If you prefer unopinionated primitives — essentially `staffer` plus `jobs` — for flexible, bidirectional delegation across `agy`, `codex`, `claude`, and `dsh`, see [**cospan**](https://github.com/keli-wen/cospan).
- ## <img src="assets/logo/bench.svg" width="32" height="32" alt=""> Bench — Harness & Orchestration
- agy-staff Bench v1 runs Claude Code and Codex on three benchmarks, each task three ways: alone, with their own subagents, and with agy through `lead`.
- [Tech Report](https://lastwhisper.dev/en/zen-of-harness-engineering/agy-staff-bench-v1/) · [中文报告](https://lastwhisper.dev/zen-of-harness-engineering/agy-staff-bench-v1/)
- [](bench/README.md)
- > [!NOTE]
- > **Why a bench.** It runs the same tasks on different hosts, with and without agy, to answer three questions:
- > - **When to delegate.** Which tasks and which hosts gain from handing work to agy, and which are better left solo. The answers become best practices for using agy-staff.
- > - **What to fix in agy-staff.** Each run shows where delegation wastes time or tokens. Those findings go back into the plugin as fixes, and later bench versions check whether the fixes worked.
- > - **How harnesses differ.** Same prompt, same worker, different host. Gaps in the results trace back to design choices in each harness.
- **What v1 says** (one run per task and setup, so a first baseline, not a verdict):
- - **agy suits research best.** DeepSearchQA is the only benchmark where agy cut host spend on both hosts: Claude Code −39%, Codex −16%. Host spend is what your Claude or ChatGPT plan pays.
- - **Claude Code's harness suits agy better.** With agy, Claude Code's host spend fell on all three benchmarks (−16% to −39%). Codex's rose on two (SWE-bench +86%, QnA +22%). Claude Code waits in the background until the agy job ends; Codex polls, and every wake-up carries its full context.
- - **The price is time.** Median time per task rose from 2–8 minutes alone to 13–26 minutes with agy. Tasks solved matched solo or dropped by one.
- **Method, caveats and versions →** [bench/README.md](bench/README.md)
- ## How
- ### Invoke a persona
- Type `/agy:` in Claude Code and the orchestration modes and personas are right there:
- 
- Same plugin in Codex, invoked with `$agy`:
- 
- In DeepSeek Harness, with the visual `agy staff` subagent sidebar and `/agy-*` role cards:
- 
- ### Install
- #### For humans
- Step 1 — install the Antigravity CLI ([official docs](https://antigravity.google/docs/cli/install)), then verify with `agy --version`. Node.js is also required:
- ```bash
- curl -fsSL https://antigravity.google/cli/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 72 on GitHub
- ```
- Step 2 — install the plugin into your harness:
- ```bash
- claude plugin marketplace add keli-wen/agy-staff
- claude plugin install agy@agy-staff
- ```
- ```bash
- codex plugin marketplace add https://github.com/keli-wen/agy-staff
- codex plugin add agy@agy-staff
- ```
- <details>
- <summary>Using DeepSeek Harness?</summary>
- Install in the **DeepSeek Harness** desktop app (**Plugins** in the left sidebar → install from package spec `github:keli-wen/agy-staff`), or from the terminal:
- ```bash
- dsh plugin --profile desktop add github:keli-wen/agy-staff
- ```
- For a local checkout during development, run `dsh plugin --profile desktop add /absolute/path/to/agy-staff` (use `--profile web` if running the web profile). `pnpm`, Node.js, and an authenticated `agy` on `PATH` are required.
- Once enabled, the plugin mounts the **`agy staff`** visual subagent right-sidebar, native Cordis tools (`agy_brain`, `agy_worker`, `agy_job`), and all eight `/agy-*` skills (`/agy-brain`, `/agy-lead`, `/agy-staffer`, `/agy-researcher`, `/agy-reviewer`, `/agy-implementer`, `/agy-ask`, `/agy-jobs`). Upgrade with `dsh plugin --profile desktop add 'github:keli-wen/agy-staff#<tag-or-commit>'`.
- </details>
- <details>
- <summary>Using Pi?</summary>
- Install: `pi install git:github.com/keli-wen/agy-staff`.
- Skills are prefixed as `/skill:agy-<persona>` (e.g. `/skill:agy-ask reply with OK`), including `/skill:agy-lead`, `/skill:agy-brain`, and `/skill:agy-jobs` for job management.
- Update with `pi update --extension git:github.com/keli-wen/agy-staff`, then run `/reload`.
- </details>
- <details>
- <summary>Using OpenCode?</summary>
- With OpenCode V1 (verified on 1.18.34), install the package through its native plugin manager:
- ```bash
- opencode plugin 'agy-staff@git+https://github.com/keli-wen/agy-staff.git' --global
- ```
- Restart OpenCode, then run `/agy-ask reply with OK`. The plugin automatically registers all eight `agy-*` skills and their native slash commands, including `/agy-lead`, `/agy-brain`, and `/agy-jobs`. No separate skills path or command wrappers are needed. Node.js and an authenticated `agy` are required, as above.
- OpenCode caches the complete package spec. Restarting does not refresh an unchanged Git spec. To upgrade, choose a newer Git tag or commit and run `opencode plugin 'agy-staff@git+https://github.com/keli-wen/agy-staff.git#<tag-or-commit>' --global --force`, then restart. See [the reference](docs/REFERENCE.md#opencode) for config and local development. OpenCode V2 is not covered by this adapter.
- </details>
- Restart Claude Code or Codex afterwards. First run: `/agy:ask reply with OK` (Claude Code) or `$agy:ask reply with OK` (Codex). Ask is tool-free and needs no setup.
- > [!IMPORTANT]
- > **There is no mandatory setup step.** `staffer`, `researcher`, `reviewer` and `implementer` run **unrestricted** by default: agy can inspect the repo, run commands, and edit files. agy-staff keeps that practical with prompts that adapt to the current repo state. For example, when `implementer` starts in a dirty workspace, the companion tells agy which files already had changes and reminds it not to overwrite or deliver unrelated user work. If the task asks for a commit, push, or PR, agy can do that delivery; otherwise it leaves a working-tree diff for review. These prompt instructions do not provide permission isolation.
- > `setup` + `--restricted` is **optional hardening** for untrusted input — per run (`--restricted`) or as a per-repo default (`setup --restrict review,research`). `setup` dry-runs and asks before writing anything ("set up agy" triggers it); read the [permission notes](docs/REFERENCE.md#optional-hardening-setup) first — the allowlist is prefix-matched, applies machine-wide, and a restricted run can return less than an unrestricted one.
- #### For agents
- Paste this into any coding agent:
- ```
- Read the raw text of https://raw.githubusercontent.com/keli-wen/agy-staff/master/docs/INSTALL_FOR_AGENTS.md (curl it — do not
- work from a summary) and follow it to install and verify the agy-staff plugin for the harness you are running in.
- Respond in the user's language.
- ```
- #### Upgrade
- Claude Code and Codex install a *copy*, so a new version only reaches you when you pull it in yourself:
- ```bash
- claude plugin marketplace update agy-staff && claude plugin update agy@agy-staff
- ```
- ```bash
- codex plugin marketplace upgrade && codex plugin add agy@agy-staff # then restart Codex
- ```
- Claude Code and Codex cache per version directory, so an upgrade lands only if the plugin version changed; restart the harness afterwards. If a fix does not show up, see [upgrading](docs/REFERENCE.md#upgrading) — it has the force-refresh command.
- ### CUJs
- Examples below use Claude Code's `/agy:…`; in Codex use `$agy:…`, in Pi `/skill:agy-…`, and in DeepSeek Harness or OpenCode `/agy-…`.
- | Use case | Invocation |
- |---|---|
- | <img src="assets/icons/lead.svg" width="16" height="16" alt=""> Lead an ongoing task | `/agy:lead investigate the options, draft a proposal, and revise it with my feedback` |
- | <img src="assets/icons/brain.svg" width="16" height="16" alt=""> Ask Carbon / Argon to propose the route | `/agy:brain design a migration; check the assumptions before implementing` |
- | Quick second opinion | `/agy:ask what's your backend model` |
- | A general task | `/agy:staffer summarize the open TODOs in this repo` |
- | Generate an image | `/agy:staffer generate a pixel-art robot mascot, save it as assets/mascot.png` |
- | Review the working tree | `/agy:reviewer Review the current working tree` |
- | Review a PR | `/agy:reviewer Review PR #730` |
- | Review a plan or decision | `/agy:reviewer Challenge the migration plan in docs/plan.md` |
- | Survey a topic | `/agy:researcher how does auth work in this repo` |
- | Implement a scoped fix | `/agy:implementer fix the flaky retry test` |
- | Job ops (wait/status/cancel/continue) | natural language: "is the agy job done?", "continue: also check the error path" |
- `reviewer` is fully prompt-based: you describe the subject and agy gathers the evidence itself (`gh pr view`, `git diff`, reading the file) — there is no flag for handing it a diff. It has two flavors, routed by subject: code review (severity-ranked findings) and general review (a multi-angle challenge of a plan, design, or decision).
- `staffer` also covers agy's native tools without a dedicated specialist persona, including **image generation** (`generate_image`). A trial on agy v1.1.15 produced a 1024×1024 PNG in about 30 seconds; actual time depends on the task and environment.
- ## Core design
- `lead` adds task orchestration guidance for your current agent. Within lead, orient enough to frame the assignment, delegate substantive work to `staffer` by default, wait for the result, then assess it and integrate or follow up. Specialists provide dedicated guidance when useful, while `ask` is reserved for testing. The host owns cross-task decisions, acceptance, integration, and delivery, using the existing jobs workflow.
- With `brain`, <img src="assets/icons/carbon.svg" width="16" height="16" alt=""> **Carbon** (or <img src="assets/icons/argon.svg" width="16" height="16" alt=""> **Argon** via `--model argon`) proposes the route first. The host supplies the goal and evidence, challenges assumptions before execution, and owns verification. See the [brain skill](skills/brain/SKILL.md).
- `ask` answers in the same call. The other personas return a job id and a collection command, such as `wait <id> --timeout 10m`. Your agent waits using the host's available capabilities, with one independent background wait per job where supported.
- The main agent waits for the final result by default. If you explicitly ask about progress, it can use `observe` to read a snapshot of recent tool activity and response text; it does not query progress for routine updates. Once the task finishes, `wait` or `result` delivers the full report. Expiring a wait leaves the worker running.
- The timeline below follows a background task from delegation to completion. The host agent waits for the final result by default (or advances already-identified independent work), checks progress when asked, and collects the report.
- [](assets/integration.svg)
- Jobs have a separate execution deadline: default 60 minutes, configurable at launch with `--timeout` up to 120 minutes. Use `cancel` to stop execution, or explicitly request `continue` or `restart` after inspecting the existing work. The host harness controls when your agent receives a background result.
- **Full reference →** [docs/REFERENCE.md](docs/REFERENCE.md) (flags, permission model, jobs/state, troubleshooting, upgrading). **Release notes →** [docs/releases/](docs/releases/).
- ## Build one for another CLI
- agy-staff's design is portable: bash plus skills, with no hard dependency on a host, a worker CLI or a runtime library ([**cospan**](https://github.com/keli-wen/cospan) already generalizes its `staffer` and `jobs` primitives across `agy`, `codex`, `claude`, and `dsh`). [docs/DESIGN.md](docs/DESIGN.md) writes the pattern down as best practice. To build a dedicated tool like this for another agent CLI, give your coding agent this prompt:
- ```
- Read the raw text of https://raw.githubusercontent.com/keli-wen/agy-staff/master/docs/DESIGN.md
- (curl it — do not work from a summary). Then design an integration that lets this host agent delegate
- work to <CLI> the same way. First read `<CLI> --help`, map what the CLI supports to the section
- "What depends on the worker CLI", and list the principles it cannot support before writing any code.
- Ask me before any call that spends model quota. Respond in the user's language.
- ```
- Before writing any code, the agent lists the principles your CLI cannot support, so you know up front where the tool will degrade.
- ## Community
- - [LINUX DO](https://linux.do/) — A next-generation Linux community.
- ## Contributing
- Contributions are welcome — issues, bug reports and pull requests all help.
- A few things worth knowing before you open a PR:
- - **Run the tests**: `npm test`. The standard suite uses temporary repos and HOME directories with fake `agy`, plus focused module tests. Keep regression tests offline and independent of personal settings. Real AGY validation is a separate opt-in suite described in [tests/README.md](tests/README.md).
- - **Docs come in pairs**: `README.md` / `README.zh-CN.md` and `docs/REFERENCE.md` / `docs/REFERENCE.zh-CN.md` are kept in sync. Change one, change its counterpart.
- - **Runtime code lives in `companion/`**: the entrypoint handles modes and job commands; separate modules handle streaming execution, observations and state locking. Skills call the companion, and `templates/` holds the shared prompts.
- - **Canonical skills are the source of truth**: edit personas in `skills/`, never in `pi-skills/` or `opencode-skills/`. Run `npm run generate:skills` to generate both host entrypoints, and `npm run check:skills` to verify consistency. The existing `generate:pi` and `check:pi` commands remain available. Use `npm run pack:checked` to check freshness before packing; publishing also runs the check.
- Adding a mode or a flag changes the public surface, so please open an issue first and we can agree on the shape.
- ## License
- MIT — see [LICENSE](LICENSE).
scripts/generate-skills.mjs · Bundled script · 191 lines · 2 findings marked
- #!/usr/bin/env node
- // Generate flat, branded skill entrypoints from the canonical methods.
- // Both targets stay at the same depth so shared runtime paths remain valid.
- import fs from 'node:fs';
- import path from 'node:path';
- import { fileURLToPath } from 'node:url';
- export const ROOT = path.resolve(fileURLToPath(new URL('../', import.meta.url)));
- export const COMPATIBILITY_CONTEXT = fs.readFileSync(new URL('../templates/harness-compatibility.md', import.meta.url), 'utf8');
- export const SHARED_START = '<!-- BEGIN SHARED PERSONA RULES -->';
- Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
- Line 10 on GitHub
- export const SHARED_END = '<!-- END SHARED PERSONA RULES -->';
- Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
- Line 11 on GitHub
- export const DIRECT_PERSONAS = ['ask', 'implementer', 'researcher', 'reviewer', 'staffer'];
- const NON_PERSONA_SKILLS = new Set(['brain', 'jobs', 'lead']);
- // Canonical SKILL.md files are installed directly by Claude Code and Codex.
- // Only their marked block is generated; everything outside stays hand-written.
- export function generateCanonicalSkills({ root = ROOT, check = false } = {}) {
- const skills = path.join(root, 'skills');
- const sharedPath = path.join(root, 'templates/persona-skill-rules.md');
- if (!fs.existsSync(sharedPath)) throw new Error('Missing shared persona rules source: templates/persona-skill-rules.md');
- const shared = fs.readFileSync(sharedPath, 'utf8').trim();
- if (!shared || shared.includes(SHARED_START) || shared.includes(SHARED_END)) {
- throw new Error('Invalid shared persona rules source');
- }
- const allSkillFiles = filesUnder(skills); // Reject symlinks before writing sources.
- for (const file of allSkillFiles) {
- if (!file.endsWith('.md')) continue;
- const relative = path.relative(root, file);
- const skillName = path.basename(path.dirname(file));
- const isDirectPersonaEntry = path.basename(file) === 'SKILL.md'
- && path.dirname(path.dirname(file)) === skills
- && !NON_PERSONA_SKILLS.has(skillName);
- if (!isDirectPersonaEntry) {
- const text = fs.readFileSync(file, 'utf8');
- if (text.includes(SHARED_START) || text.includes(SHARED_END)) {
- throw new Error(`Unexpected shared persona rules block in ${relative}`);
- }
- }
- }
- const entryPaths = new Set(DIRECT_PERSONAS.map(name => path.join(skills, name, 'SKILL.md')));
- for (const file of allSkillFiles) {
- if (path.basename(file) === 'SKILL.md' && path.dirname(path.dirname(file)) === skills) {
- const text = fs.readFileSync(file, 'utf8');
- if (text.includes(SHARED_START) || text.includes(SHARED_END)) entryPaths.add(file);
- }
- }
- const entries = [...entryPaths].sort().map(output => {
- const relative = path.relative(root, output);
- if (!fs.existsSync(output)) throw new Error(`Missing expected persona skill: ${relative}`);
- return { output, relative, source: fs.readFileSync(output, 'utf8') };
- });
- const block = `${SHARED_START}\n<!-- Generated from templates/persona-skill-rules.md; run npm run generate:skills. Do not edit this block. -->\n${shared}\n${SHARED_END}`;
- const outputs = [];
- for (const { output, relative, source } of entries) {
- const start = source.indexOf(SHARED_START);
- const end = source.indexOf(SHARED_END);
- if (start < 0 || end < start || source.indexOf(SHARED_START, start + 1) !== -1 || source.indexOf(SHARED_END, end + 1) !== -1) {
- throw new Error(`Expected exactly one ordered shared rules block in ${relative}`);
- }
- const dispatchExample = source.indexOf('## Locating the companion');
- if (dispatchExample === -1 || start > dispatchExample) {
- throw new Error(`Shared rules block must appear before dispatch example in ${relative}`);
- }
- const content = source.slice(0, start) + block + source.slice(end + SHARED_END.length);
- if (content !== source) outputs.push({ relative, output, content });
- }
- if (check && outputs.length) {
- throw new Error(`Stale canonical persona rules; edit templates/persona-skill-rules.md and run npm run generate:skills:\n${outputs.map(item => item.relative).join('\n')}`);
- }
- for (const { output, content } of outputs) fs.writeFileSync(output, content);
- return { changed: outputs.map(item => item.relative) };
- }
- function filesUnder(dir) {
- if (!fs.existsSync(dir)) return [];
- if (fs.lstatSync(dir).isSymbolicLink()) throw new Error(`Do not generate through symlinks: ${dir}`);
- return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
- const target = path.join(dir, entry.name);
- if (entry.isSymbolicLink()) throw new Error(`Do not generate through symlinks: ${target}`);
- return entry.isDirectory() ? filesUnder(target) : [target];
- });
- }
- const targets = {
- pi: {
- label: 'Pi', outputDir: 'pi-skills', namePrefix: 'agy-', invocationPrefix: '/skill:',
- dropMetadata: ['allowed-tools', 'argument-hint', 'user-invocable'], appendCompatibility: true,
- },
- opencode: {
- label: 'OpenCode', outputDir: 'opencode-skills', namePrefix: 'agy-', invocationPrefix: '/',
- dropMetadata: ['allowed-tools', 'argument-hint', 'user-invocable'], appendCompatibility: true,
- },
- };
- export function skillFiles(root = ROOT, target) {
- if (!Object.hasOwn(targets, target)) throw new Error(`Unknown skill target: ${target}`);
- const host = targets[target];
- const { outputDir, namePrefix, invocationPrefix } = host;
- const source = path.join(root, 'skills');
- const names = fs.readdirSync(source).filter(name => fs.existsSync(path.join(source, name, 'SKILL.md'))).sort();
- const outputs = new Map();
- for (const name of names) {
- const generatedName = `${namePrefix}${name}`;
- if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || generatedName.length > 64) {
- throw new Error(`Invalid ${host.label} skill name: ${generatedName}`);
- }
- for (const file of filesUnder(path.join(source, name))) {
- let content = fs.readFileSync(file);
- if (file.endsWith('.md')) {
- content = content.toString('utf8');
- // Change only skill invocation syntax and skill-directory paths, never
- // companion subcommands such as `review`, `research`, or `wait`.
- for (const peer of names) {
- content = content.replace(new RegExp(`(?:/agy:|\\$agy:)${peer}(?![a-z0-9-])`, 'g'), `${invocationPrefix}${namePrefix}${peer}`)
- .replaceAll(`../${peer}/`, `../${namePrefix}${peer}/`)
- .replaceAll(`<plugin-root>/skills/${peer}/`, `<plugin-root>/${outputDir}/${namePrefix}${peer}/`);
- }
- const canonicalRel = path.relative(root, file).split(path.sep).join('/');
- const notice = `<!-- Generated from ${canonicalRel}; run npm run generate:${target}. Do not edit here. -->`;
- const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
- if (path.basename(file) === 'SKILL.md') {
- if (!match || !match[1].split('\n').includes(`name: ${name}`)) {
- throw new Error(`Expected name: ${name} in ${file}`);
- }
- const frontmatter = match[1].split('\n')
- // These are Claude-specific UI/permission fields, not host policy.
- .filter(line => !host.dropMetadata.includes(line.split(':', 1)[0]))
- .map(line => line === `name: ${name}` ? `name: ${generatedName}` : line).join('\n');
- content = `---\n${frontmatter}\n---\n\n${notice}\n`
- + content.slice(match[0].length)
- + (host.appendCompatibility ? '\n' + COMPATIBILITY_CONTEXT : '');
- } else if (match) {
- content = `---\n${match[1]}\n---\n\n${notice}\n` + content.slice(match[0].length);
- } else {
- content = `${notice}\n\n${content}`;
- }
- content = Buffer.from(content);
- }
- outputs.set(path.join(outputDir, generatedName, path.relative(path.join(source, name), file)), content);
- }
- }
- return outputs;
- }
- export function generateSkills({ root = ROOT, check = false, target } = {}) {
- if (!Object.hasOwn(targets, target)) throw new Error(`Unknown skill target: ${target}`);
- const hasSharedSource = fs.existsSync(path.join(root, 'templates/persona-skill-rules.md'))
- || filesUnder(path.join(root, 'skills')).some(file => file.endsWith('.md') && (fs.readFileSync(file, 'utf8').includes(SHARED_START) || fs.readFileSync(file, 'utf8').includes(SHARED_END)));
- const canonical = hasSharedSource ? generateCanonicalSkills({ root, check }) : { changed: [] };
- const expected = skillFiles(root, target);
- const host = targets[target];
- const actual = filesUnder(path.join(root, host.outputDir));
- const unexpected = actual.filter(file => !expected.has(path.relative(root, file)));
- // Fail instead of deleting stale files automatically: a maintainer may have
- // edited them. Renames/removals must explicitly remove the obsolete output.
- if (unexpected.length) throw new Error(`Unexpected generated files; inspect and remove explicitly:\n${unexpected.join('\n')}`);
- const changed = [];
- for (const [relative, content] of expected) {
- const output = path.join(root, relative);
- if (fs.existsSync(output) && fs.readFileSync(output).equals(content)) continue;
- changed.push(relative);
- if (!check) {
- fs.mkdirSync(path.dirname(output), { recursive: true });
- fs.writeFileSync(output, content);
- }
- }
- if (check && changed.length) {
- throw new Error(`Stale ${host.label} skills; edit canonical sources in skills/ (do not edit ${host.outputDir}/) and run npm run generate:${target}:\n${changed.join('\n')}`);
- }
- return { count: expected.size, changed, canonicalChanged: canonical.changed };
- }
- if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
- try {
- const args = process.argv.slice(2);
- const supported = ['all', ...Object.keys(targets)];
- const selectors = args.filter(arg => arg.startsWith('--target='));
- if (selectors.length > 1 || args.some(arg => arg !== '--check' && !supported.some(target => arg === `--target=${target}`))) {
- throw new Error(`Usage: generate-skills.mjs [--check] [--target=${supported.join('|')}]`);
- }
- const selected = selectors[0]?.slice(9) || 'all';
- const check = args.includes('--check');
- for (const target of selected === 'all' ? Object.keys(targets) : [selected]) {
- const result = generateSkills({ check, target });
- console.log(`${targets[target].label} skills ${check ? 'verified' : 'generated'}: ${result.count} files (${result.changed.length} changed).`);
- }
- } catch (error) {
- console.error(error.message);
- process.exitCode = 1;
- }
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.