docs(external-tool-integration): add Hermes Agent as worked example#253
Merged
Conversation
README.md already lists Hermes Agent alongside OpenClaw as a supported external harness for driving CAO via the cao-session-management skill, but external-tool-integration.md only walked through OpenClaw. Add Hermes target paths to Options A and C so the doc matches the README's supported-harness list. - Option A: add commented Hermes TARGET_SKILLS path (~/.hermes/skills/cli-agent-orchestrator) - Option C: add Hermes-specific skill_manage invocation and note the copy-vs-symlink staleness tradeoff - Intro: name both OpenClaw and Hermes Agent as worked examples Verified end-to-end on Hermes: launched code_supervisor + developer + reviewer via cao launch --headless --yolo on the kiro_cli provider and produced a working hello.py.
…to cao-session-management Agents loading the skill cold currently have to assemble a working 'cao launch' from rules scattered through the doc, and silently assume two prerequisites that fail confusingly when missing: - cao-server must be running at localhost:9889 - the target agent profile must already be installed via cao install Add three additive sections before 'Launching a Session': 1. **Prerequisites** — explicit cao-server health check (curl one-liner) and a reminder that profiles must be pre-installed. 2. **Discovering Available Profiles** — table of where to look depending on provider (kiro-cli agent list, agent-store/, README built-ins). 3. **Quick Example** — copy-pasteable end-to-end supervisor launch on the default kiro_cli provider, plus status/shutdown commands. No existing content removed; these are anchors a first-time agent can grab onto before reading the rules section. Verified against the skill end-to-end on Hermes Agent: launched code_supervisor + developer + reviewer headlessly and produced a working hello.py in 2m 38s.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the external tool integration documentation to include Hermes Agent as an additional worked example for consuming CAO SKILL.md skills.
Changes:
- Expand the intro to reference both OpenClaw and Hermes Agent as worked examples.
- Add a Hermes Agent
TARGET_SKILLSpath example in the symlink setup. - Add Hermes Agent–specific guidance for registering the skill into Hermes’s local skill store.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The previous skill update leaned too heavily on kiro_cli, but profiles in CAO are provider-agnostic — 'cao install' is the canonical install path for any provider, and ~/.aws/cli-agent-orchestrator/agent-store/ is the source of truth for what's installed locally. Workers inherit the launching terminal's provider unless pinned via frontmatter (README §Cross-Provider Orchestration). Changes: - Discovering Available Profiles: lead with the provider-agnostic agent-store/ listing and built-in install commands; demote 'kiro-cli agent list' to a provider-specific note (CAO mirrors profiles into ~/.kiro/agents/, which is why it works for kiro_cli). - Quick Example: keep kiro_cli as the default but enumerate every supported provider for --provider, and add a commented cross-provider variant so claude_code / codex / gemini_cli / kimi_cli / copilot_cli / opencode_cli / q_cli users see themselves in the doc. - Launching rule: replace the kiro-only --agents discovery hint with a cross-link to the new section.
Contributor
Author
|
@anilkmr-a2z when you get a chance can you help to review this ? |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Per Copilot review on PR #253: `cao install <built-in>` writes to `agent-context/`, not `agent-store/`. The latter only holds custom local profile files. The HTTP endpoint `/agents/profiles` is the canonical, provider-agnostic way to see all installed profiles with `source` labels (built-in vs local). - Promote `curl /agents/profiles` as the recommended check - Split filesystem rows into agent-store (local) vs agent-context (built-ins) - Add explanatory note below the table
anilkmr-a2z
approved these changes
May 21, 2026
| | Built-in profiles you can install | see [README — Quick Start](../../README.md#quick-start) (`code_supervisor`, `developer`, `reviewer`, …) | | ||
| | Provider-native list (`kiro_cli` only) | `kiro-cli agent list` — useful because CAO mirrors profiles into `~/.kiro/agents/` | | ||
|
|
||
| The HTTP endpoint is the recommended check: it merges built-ins (installed via `cao install`, which writes to `agent-context/`) with custom profile files (in `agent-store/`) and returns both with a `source` field. |
Contributor
There was a problem hiding this comment.
Correct! I even invoke it from my Mac and CAO running on desktop.
|
|
||
| If unsure which profile to use, ask the user rather than guessing. | ||
|
|
||
| ## Quick Example |
Contributor
There was a problem hiding this comment.
I am worried about this section if some reason if it starts to do this. I really like this script to start on a configured cao setup.
But I understand you are trying to have some setup everything through their other configured harnesses.
Per @anilkmr-a2z review on PR #253: the Quick Example should foreground that it runs against an already-configured CAO host; `cao install` belongs to one-time setup, not to every launch. - Add note above the code block stating the example assumes a configured CAO setup and that users can skip to `cao launch` on an already-configured host. - Re-frame the install lines as Optional first-time setup rather than mandatory pre-launch steps.
Per Copilot review on PR #253: the previous wording overstated the endpoint's behavior. `list_agent_profiles()` actually scans three sources (built-in packaged store, local agent-store, provider directories including agent-context) and de-duplicates by profile name (built-in wins), rather than "merging" two specific dirs. - Reword the table row to "all available profiles across built-in store + local store + provider directories" - Reword the explanatory paragraph to describe the three-source scan and dedup behavior accurately
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add Hermes Agent as a second worked example (alongside OpenClaw) for consuming CAO
SKILL.mdskills, and tighten thecao-session-managementskill itself so any external agent loading it cold has a clearer on-ramp.Changes
docs/external-tool-integration.mdTARGET_SKILLSpath example.skill_manage(...)example that reads the SKILL.md from disk viaPath('~/.aws/cli-agent-orchestrator/skills/cao-session-management/SKILL.md').expanduser().read_text()so it's concretely runnable (Copilot Autofix).skills/cao-session-management/SKILL.md## Prerequisitessection with acurlone-liner to verifycao-serveris up atlocalhost:9889, plus a reminder that profiles must be installed first.## Discovering Available Profilessection as a provider-agnostic table:curl /agents/profiles(canonical — merges built-in + local withsourcelabels)~/.aws/cli-agent-orchestrator/agent-store/(custom/local profiles)~/.aws/cli-agent-orchestrator/agent-context/(built-ins installed viacao install)kiro-cli agent list(provider-native, kiro_cli only)## Quick Examplesection: copy-pasteable end-to-end supervisor launch, with a commented variant showing how to swap providers via--provider.No existing content removed or reordered. The "Launching a Session" rules section is unchanged.
Why
The current skill jumps straight to "Launching a Session" but silently assumes two prerequisites that fail confusingly when missing:
cao-servermust be running atlocalhost:9889— otherwisecao launchhangs / errors with no clue why.cao launch --agents code_supervisorfails ifcao install code_supervisorhasn't been run.A first-time agent loading the skill also had to mentally assemble a working
cao launchfrom rules scattered across the bullet list. A copy-pasteable example removes that friction.Verification
End-to-end tested via Hermes Agent driving CAO with the default
kiro_cliprovider:code_supervisor→ handed off todeveloper→ handed off toreviewerhello.pyprintingHello, World!completedstatus;cao shutdown --session cao-hello-worldcleaned up successfullyProfile-discovery fix (commit
67011e5) verified empirically:ls ~/.aws/cli-agent-orchestrator/agent-store/→ local profiles onlyls ~/.aws/cli-agent-orchestrator/agent-context/→ built-ins installed viacao installcurl /agents/profiles→ both, withsource: built-in|localScope
Documentation only. No code changes.