docs: add AO agent plugin builder skill#1722
docs: add AO agent plugin builder skill#1722yyovil wants to merge 1 commit intoComposioHQ:mainComposioHQ/agent-orchestrator:mainfrom yyovil:feat/ao-agent-plugin-builder-skillyyovil/agent-orchestrator:feat/ao-agent-plugin-builder-skillCopy head branch name to clipboard
Conversation
Greptile SummaryThis PR adds a repo-local
Confidence Score: 4/5Safe to merge; changes are documentation and a helper script with no impact on production code paths. The docs and YAML are clean and consistent. The Python smoke-checker has two issues in check_central_wiring(): unguarded read() calls that crash instead of recording FAILs when a checked file is absent, and order-sensitive regexes that will falsely FAIL correctly-wired plugins whose object properties appear in a different sequence. Neither affects any production behavior, but they do undermine the reliability of the validation tool this skill asks developers to run. skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py — check_central_wiring() needs error handling for missing files and order-independent property matching in its regex patterns.
|
| Filename | Overview |
|---|---|
| skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py | Smoke-checker for built-in agent wiring; has two logic issues — unguarded read() calls in check_central_wiring() can crash instead of FAILing, and registry/detect regex patterns require a fixed property order that could produce false FAILs. |
| skills/ao-agent-plugin-builder/SKILL.md | Main skill definition with workflow, source-truth references, and guardrails; well-structured and accurate relative to the repo's plugin patterns. |
| skills/ao-agent-plugin-builder/agents/openai.yaml | Minimal OpenAI agent interface config; display name and default prompt are consistent with SKILL.md. |
| skills/ao-agent-plugin-builder/references/patterns.md | Template-selection matrix, monorepo package shape, activity-state pattern, and common pitfalls; accurate and useful reference for implementing new agent plugins. |
| skills/ao-agent-plugin-builder/references/checklist.md | Comprehensive per-plugin implementation checklist covering CLI research through validation commands; no issues found. |
| skills/ao-agent-plugin-builder/references/amp-example.md | Worked first-target recommendation for Amp; correctly scoped as a guide rather than a prescription, with appropriate caveats to verify CLI behavior before coding. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A([Developer invokes skill]) --> B[SKILL.md: Classify target CLI]
B --> C[references/patterns.md: Choose closest template]
C --> D[Copy packages/plugins/agent-slug]
D --> E[Implement full Agent contract]
E --> F[Wire AO surfaces]
F --> F1[packages/core/src/plugin-registry.ts]
F --> F2[packages/cli/package.json]
F --> F3[packages/cli/src/lib/detect-agent.ts]
F --> F4[packages/web/src/lib/services.ts]
F --> F5[plugin-registry.json optional]
F --> F6[start.ts optional]
F1 & F2 & F3 & F4 & F5 & F6 --> G[references/checklist.md: Verify all steps]
G --> H[scripts/check_agent_plugin_wiring.py slug]
H --> I{All FAILs = 0?}
I -- Yes --> J[pnpm typecheck / test / build]
I -- No --> E
J --> K([PR ready])
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py:101-135
**Unhandled `FileNotFoundError` crashes the checker instead of recording a FAIL**
`check_central_wiring()` calls `self.read(...)` for every central file without guarding against missing files. `read()` calls `Path.read_text()` directly, which raises `FileNotFoundError` if the file does not exist. A developer running the script against a new plugin whose marketplace/start.ts entries haven't been created yet — or from a directory where a file path is unexpectedly absent — will get a Python traceback instead of a structured FAIL/WARN output, hiding all subsequent checks. At minimum the files that drive `warn_if_missing` (`plugin-registry.json`, `start.ts`) could plausibly be absent if the CLI package hasn't been set up yet; a crash there skips the PASS/FAIL summary entirely.
### Issue 2 of 2
skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py:107-118
**Regex checks require a fixed property order that may not match real source formatting**
`registry_pattern` requires `slot` then `name` then `pkg` in that exact order; `detect_pattern` requires `name` then `pkg`. If a developer (or a formatter) writes the object with properties in alphabetical or any other order — e.g. `{ name: "amp", slot: "agent", pkg: "..." }` in `plugin-registry.ts` — both patterns will FAIL even though the plugin is correctly wired. The script is supposed to be the authoritative smoke-check, so a spurious FAIL caused by property ordering is likely to erode trust in the tool. Consider matching the three properties independently (separate `re.search` for each) rather than in a single sequence.
Reviews (1): Last reviewed commit: "docs: add AO agent plugin builder skill" | Re-trigger Greptile
| def check_central_wiring(self) -> None: | ||
| cli_package = json.loads(self.read("packages/cli/package.json")) | ||
| deps = cli_package.get("dependencies", {}) | ||
| self.require(deps.get(self.package_name) == "workspace:*", "packages/cli/package.json has workspace dependency") | ||
|
|
||
| registry = self.read("packages/core/src/plugin-registry.ts") | ||
| registry_pattern = ( | ||
| rf'\{{\s*slot:\s*"agent",\s*name:\s*"{re.escape(self.slug)}",' | ||
| rf'\s*pkg:\s*"{re.escape(self.package_name)}"\s*\}}' | ||
| ) | ||
| self.require(re.search(registry_pattern, registry) is not None, "core BUILTIN_PLUGINS includes agent") | ||
|
|
||
| detect_agent = self.read("packages/cli/src/lib/detect-agent.ts") | ||
| detect_pattern = ( | ||
| rf'\{{\s*name:\s*"{re.escape(self.slug)}",' | ||
| rf'\s*pkg:\s*"{re.escape(self.package_name)}"\s*\}}' | ||
| ) | ||
| self.require(re.search(detect_pattern, detect_agent) is not None, "CLI AGENT_PLUGINS includes agent") | ||
|
|
||
| services = self.read("packages/web/src/lib/services.ts") | ||
| import_name = slug_to_import_name(self.slug) | ||
| self.require(self.package_name in services, "web services statically import package") | ||
| self.require(f"registry.register({import_name})" in services, f"web services register {import_name}") | ||
|
|
||
| marketplace = self.read("packages/cli/src/assets/plugin-registry.json") | ||
| self.warn_if_missing( | ||
| self.package_name in marketplace, | ||
| "marketplace catalog includes package when installer-visible", | ||
| ) | ||
|
|
||
| start_ts = self.read("packages/cli/src/commands/start.ts") | ||
| self.warn_if_missing( | ||
| f'id: "{self.slug}"' in start_ts, | ||
| "ao start install options include agent when install command is known", | ||
| ) |
There was a problem hiding this comment.
Unhandled
FileNotFoundError crashes the checker instead of recording a FAIL
check_central_wiring() calls self.read(...) for every central file without guarding against missing files. read() calls Path.read_text() directly, which raises FileNotFoundError if the file does not exist. A developer running the script against a new plugin whose marketplace/start.ts entries haven't been created yet — or from a directory where a file path is unexpectedly absent — will get a Python traceback instead of a structured FAIL/WARN output, hiding all subsequent checks. At minimum the files that drive warn_if_missing (plugin-registry.json, start.ts) could plausibly be absent if the CLI package hasn't been set up yet; a crash there skips the PASS/FAIL summary entirely.
Prompt To Fix With AI
This is a comment left during a code review.
Path: skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py
Line: 101-135
Comment:
**Unhandled `FileNotFoundError` crashes the checker instead of recording a FAIL**
`check_central_wiring()` calls `self.read(...)` for every central file without guarding against missing files. `read()` calls `Path.read_text()` directly, which raises `FileNotFoundError` if the file does not exist. A developer running the script against a new plugin whose marketplace/start.ts entries haven't been created yet — or from a directory where a file path is unexpectedly absent — will get a Python traceback instead of a structured FAIL/WARN output, hiding all subsequent checks. At minimum the files that drive `warn_if_missing` (`plugin-registry.json`, `start.ts`) could plausibly be absent if the CLI package hasn't been set up yet; a crash there skips the PASS/FAIL summary entirely.
How can I resolve this? If you propose a fix, please make it concise.| registry_pattern = ( | ||
| rf'\{{\s*slot:\s*"agent",\s*name:\s*"{re.escape(self.slug)}",' | ||
| rf'\s*pkg:\s*"{re.escape(self.package_name)}"\s*\}}' | ||
| ) | ||
| self.require(re.search(registry_pattern, registry) is not None, "core BUILTIN_PLUGINS includes agent") | ||
|
|
||
| detect_agent = self.read("packages/cli/src/lib/detect-agent.ts") | ||
| detect_pattern = ( | ||
| rf'\{{\s*name:\s*"{re.escape(self.slug)}",' | ||
| rf'\s*pkg:\s*"{re.escape(self.package_name)}"\s*\}}' | ||
| ) | ||
| self.require(re.search(detect_pattern, detect_agent) is not None, "CLI AGENT_PLUGINS includes agent") |
There was a problem hiding this comment.
Regex checks require a fixed property order that may not match real source formatting
registry_pattern requires slot then name then pkg in that exact order; detect_pattern requires name then pkg. If a developer (or a formatter) writes the object with properties in alphabetical or any other order — e.g. { name: "amp", slot: "agent", pkg: "..." } in plugin-registry.ts — both patterns will FAIL even though the plugin is correctly wired. The script is supposed to be the authoritative smoke-check, so a spurious FAIL caused by property ordering is likely to erode trust in the tool. Consider matching the three properties independently (separate re.search for each) rather than in a single sequence.
Prompt To Fix With AI
This is a comment left during a code review.
Path: skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py
Line: 107-118
Comment:
**Regex checks require a fixed property order that may not match real source formatting**
`registry_pattern` requires `slot` then `name` then `pkg` in that exact order; `detect_pattern` requires `name` then `pkg`. If a developer (or a formatter) writes the object with properties in alphabetical or any other order — e.g. `{ name: "amp", slot: "agent", pkg: "..." }` in `plugin-registry.ts` — both patterns will FAIL even though the plugin is correctly wired. The script is supposed to be the authoritative smoke-check, so a spurious FAIL caused by property ordering is likely to erode trust in the tool. Consider matching the three properties independently (separate `re.search` for each) rather than in a single sequence.
How can I resolve this? If you propose a fix, please make it concise.There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3a40089603
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| self.require(self.package_name in services, "web services statically import package") | ||
| self.require(f"registry.register({import_name})" in services, f"web services register {import_name}") |
There was a problem hiding this comment.
Don't fail existing agents omitted from the dashboard
When the helper is run against the current built-in aider plugin (python3 skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py aider), these dashboard checks fail because packages/web/src/lib/services.ts intentionally/previously does not import or register aider. Since the skill lists agent-aider as a source template and describes this as a built-in wiring smoke checker, the script now returns exit 1 on a supported existing agent and can send implementers into unrelated web changes; either make this check conditional/warn-only for agents not dashboard-registered today, or align the repo first.
Useful? React with 👍 / 👎.
| - [ ] Add built-in entry in `packages/core/src/plugin-registry.ts`. | ||
| - [ ] Add CLI detection entry in `packages/cli/src/lib/detect-agent.ts`. | ||
| - [ ] Add `AGENT_INSTALL_OPTIONS` entry in `packages/cli/src/commands/start.ts` only when the install command is known and safe. | ||
| - [ ] Add static import and `registry.register(...)` in `packages/web/src/lib/services.ts`. |
There was a problem hiding this comment.
Include the web package dependency in dashboard wiring
When a new agent is statically imported here, packages/web/package.json also needs a workspace:* dependency for that package; the existing dashboard imports all have matching dependencies there. Following this checklist as written adds the services import/register but leaves filtered web installs/builds without a declared dependency on @aoagents/ao-plugin-agent-{slug}, so the dashboard can fail to resolve the new import even though the helper passes. Please add the web package dependency to the wiring instructions/checker.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR adds a repo-local “AO agent plugin builder” skill (docs + references) to standardize how new packages/plugins/agent-* plugins are created and wired into core/CLI/web surfaces, plus a Python smoke-check script to validate that wiring for a given agent slug.
Changes:
- Added
skills/ao-agent-plugin-builder/SKILL.mdwith an end-to-end workflow for implementing a single new AO agent plugin from existing repo patterns. - Added bundled reference docs (
references/patterns.md,references/checklist.md,references/amp-example.md) to guide template selection and implementation/testing steps. - Added
scripts/check_agent_plugin_wiring.pyto validate package shape and central wiring (core registry, CLI dependency + detection, web services registration, optional marketplace/install entries).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/ao-agent-plugin-builder/SKILL.md | Skill entrypoint documenting the recommended workflow, wiring surfaces, and validation commands. |
| skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py | Adds a wiring smoke-check script for agent plugin package + registry/CLI/web integration. |
| skills/ao-agent-plugin-builder/references/patterns.md | Documents existing agent-plugin templates/patterns and required wiring surfaces. |
| skills/ao-agent-plugin-builder/references/checklist.md | Step-by-step checklist for implementing and validating a new agent plugin. |
| skills/ao-agent-plugin-builder/references/amp-example.md | Worked example framing Amp as a suggested first target and how to scope that PR. |
| skills/ao-agent-plugin-builder/agents/openai.yaml | Adds skill metadata for an OpenAI/skill-runner integration surface. |
| self.require(self.package_name in services, "web services statically import package") | ||
| self.require(f"registry.register({import_name})" in services, f"web services register {import_name}") |
| self.require(f'name: "{self.slug}"' in text, "manifest.name matches slug") | ||
| self.require('slot: "agent" as const' in text, "manifest.slot is agent") | ||
| self.require("type Agent" in text or ", Agent" in text, "imports Agent type") | ||
| self.require("type PluginModule" in text or ", PluginModule" in text, "imports PluginModule type") |
| def check_central_wiring(self) -> None: | ||
| cli_package = json.loads(self.read("packages/cli/package.json")) | ||
| deps = cli_package.get("dependencies", {}) | ||
| self.require(deps.get(self.package_name) == "workspace:*", "packages/cli/package.json has workspace dependency") | ||
|
|
||
| registry = self.read("packages/core/src/plugin-registry.ts") |
Summary
ao-agent-plugin-builderskill for building new AO agent plugins from existingpackages/plugins/agent-*patternsValidation
python3 /Users/tanishqpalandurkar/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/skills/skill-creator/scripts/quick_validate.py skills/ao-agent-plugin-buildergit diff --checkpython3 -m py_compile skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.pypython3 skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py kimicodepython3 skills/ao-agent-plugin-builder/scripts/check_agent_plugin_wiring.py cursor(expected warnings for optional marketplace/install entries)Suggested first target
Amp, after verifying its real CLI help/docs for prompt, model, approval, workdir, resume, and session-log behavior.