Skip to content

docs(skills): add managed skills to README, restore developer.md orch…#170

Merged
haofeif merged 2 commits into
mainfrom
fix/skills-gaps
Apr 13, 2026
Merged

docs(skills): add managed skills to README, restore developer.md orch…#170
haofeif merged 2 commits into
mainfrom
fix/skills-gaps

Conversation

@haofeif

@haofeif haofeif commented Apr 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • README: Add "Managed Skills" section documenting cao skills CLI commands (list, add, remove, add --force), provider delivery table, and skill update instructions
  • developer.md: Restore "Multi-Agent Communication" section that was removed by feat: Add support for skills #145 — handoff/assign instructions should remain inline in the agent profile, not only in builtin skills that require cao init
  • docs/skills.md: Remove Q CLI references (deprecated), clarify builtin skill seeding behavior, use consistent language for how providers pick up skill changes

Context

PR #145 (skills feature) moved the handoff/assign/send_message instructions from developer.md into a cao-worker-protocols builtin skill. However:

  • The skills frontmatter field was never implemented, so the reference was removed in the final squash
  • The inline instructions were not restored, leaving a gap
  • The README had no documentation for cao skills commands

Test plan

  • Docs-only change — verify README renders correctly
  • Verify developer.md has the Multi-Agent Communication section restored
  • Verify docs/skills.md no longer references Q CLI

@haofeif @claude
docs(skills): add managed skills to README, restore developer.md orch…
1f3b98c 
…estration instructions

- Add "Managed Skills" section to README with cao skills CLI commands,
  provider delivery table, and update instructions
- Restore "Multi-Agent Communication" section in developer.md that was
  removed by #145 when orchestration instructions were moved to builtin
  skills — these should remain inline in the agent profile
- Update docs/skills.md: remove Q CLI references, clarify builtin skill
  seeding, use consistent provider update language across all sections

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@haofeif haofeif added the enhancement New feature or request label Apr 13, 2026
@haofeif haofeif requested a review from fanhongy April 13, 2026 08:29
@haofeif

haofeif commented Apr 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

@patricka3125 can you please help to review this ? It is just the documentation update.

Why restore the Multi-Agent Communication section in developer.md

PR #145 removed the inline handoff/assign instructions from developer.md and replaced them with a skills: [cao-worker-protocols] frontmatter reference. However, in the final squash commit, the skills frontmatter field was also removed because per-profile skill scoping was never implemented. The net result is that developer.md lost its orchestration instructions with nothing replacing them.

The cao-worker-protocols skill still exists in the package, but it only reaches the skill store if the user runs cao init — which is not part of the Quick Start flow.

Even when seeded, skills are loaded lazily and depend on the agent deciding to load them based on description matching. The handoff/assign instructions are not optional domain knowledge — they are core to how workers behave in a multi-agent session. A worker that doesn't know to call send_message after an assign task will silently fail to return results to the supervisor.

And i think in the existing ways of running cao, we dont have to run cao init, so i restore the developer.md instruciton back, for users who do not run cao init they can have seamless experience

@patricka3125

patricka3125 commented Apr 13, 2026

Copy link
Copy Markdown
Collaborator

Hey @haofeif thanks for the documentation follow up. LGTM. and yeah I decided to scope down #145 and defer the skills frontmatter support into a future change. The changes to the developer.md shouldve been reverted so thanks for catching this quickly

fanhongy
fanhongy approved these changes Apr 13, 2026
View reviewed changes
Comment thread README.md Outdated
@haofeif @claude
docs: use cao-server instead of server in README skills section
fcc146e 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@haofeif haofeif merged commit 76c2fa5 into main Apr 13, 2026
12 checks passed
@haofeif haofeif deleted the fix/skills-gaps branch April 13, 2026 10:49
erikmackinnon pushed a commit to erikmackinnon/cli-agent-orchestrator that referenced this pull request Apr 18, 2026
@haofeif @claude @erikmackinnon
docs(skills): add managed skills to README, restore developer.md orch… (
36dfd5e 
awslabs#170)

* docs(skills): add managed skills to README, restore developer.md orchestration instructions

- Add "Managed Skills" section to README with cao skills CLI commands,
  provider delivery table, and update instructions
- Restore "Multi-Agent Communication" section in developer.md that was
  removed by awslabs#145 when orchestration instructions were moved to builtin
  skills — these should remain inline in the agent profile
- Update docs/skills.md: remove Q CLI references, clarify builtin skill
  seeding, use consistent provider update language across all sections

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: use cao-server instead of server in README skills section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
(cherry picked from commit 76c2fa5)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fanhongy fanhongy fanhongy approved these changes

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@haofeif @patricka3125 @fanhongy