Skip to content

docs(external-tool-integration): add Hermes Agent as worked example#253

Merged
haofeif merged 7 commits into
mainfrom
docs/add-hermes-external-tool-example
May 21, 2026
Merged

docs(external-tool-integration): add Hermes Agent as worked example#253
haofeif merged 7 commits into
mainfrom
docs/add-hermes-external-tool-example

Conversation

@haofeif

@haofeif haofeif commented May 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Add Hermes Agent as a second worked example (alongside OpenClaw) for consuming CAO SKILL.md skills, and tighten the cao-session-management skill itself so any external agent loading it cold has a clearer on-ramp.

Changes

docs/external-tool-integration.md

  • Intro now references both OpenClaw and Hermes Agent as worked examples.
  • Option A (symlink): added a Hermes-specific TARGET_SKILLS path example.
  • Option C (copy): added a Hermes skill_manage(...) example that reads the SKILL.md from disk via Path('~/.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

  • New ## Prerequisites section with a curl one-liner to verify cao-server is up at localhost:9889, plus a reminder that profiles must be installed first.
  • New ## Discovering Available Profiles section as a provider-agnostic table:
    • curl /agents/profiles (canonical — merges built-in + local with source labels)
    • ~/.aws/cli-agent-orchestrator/agent-store/ (custom/local profiles)
    • ~/.aws/cli-agent-orchestrator/agent-context/ (built-ins installed via cao install)
    • kiro-cli agent list (provider-native, kiro_cli only)
  • New ## Quick Example section: 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-server must be running at localhost:9889 — otherwise cao launch hangs / errors with no clue why.
  • The target agent profile must already exist — cao launch --agents code_supervisor fails if cao install code_supervisor hasn't been run.

A first-time agent loading the skill also had to mentally assemble a working cao launch from 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_cli provider:

  • code_supervisor → handed off to developer → handed off to reviewer
  • Produced a working hello.py printing Hello, World!
  • Total wall-clock: 2m 38s
  • Session showed completed status; cao shutdown --session cao-hello-world cleaned up successfully

Profile-discovery fix (commit 67011e5) verified empirically:

  • ls ~/.aws/cli-agent-orchestrator/agent-store/ → local profiles only
  • ls ~/.aws/cli-agent-orchestrator/agent-context/ → built-ins installed via cao install
  • curl /agents/profiles → both, with source: built-in|local

Scope

Documentation only. No code changes.

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.
Copilot AI review requested due to automatic review settings May 21, 2026 00:58
…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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_SKILLS path 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.

Comment thread docs/external-tool-integration.md
Comment thread docs/external-tool-integration.md Outdated
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.
@haofeif

haofeif commented May 21, 2026

Copy link
Copy Markdown
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>
@haofeif haofeif added the documentation Improvements or additions to documentation label May 21, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comment thread skills/cao-session-management/SKILL.md Outdated
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
Comment thread skills/cao-session-management/SKILL.md Outdated
| 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copilot AI review requested due to automatic review settings May 21, 2026 04:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comment thread skills/cao-session-management/SKILL.md Outdated
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
@haofeif haofeif merged commit c182174 into main May 21, 2026
12 checks passed
@haofeif haofeif deleted the docs/add-hermes-external-tool-example branch May 21, 2026 06:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants