add-capability
Add a Cloudhal capability (MCP tools + policy scopes + optional REST routes and Studio panel) in packages/mcp-server, packages/agent-runtime and apps/studio. Use when adding an integration or a new set of agent tools.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- add-capability
- license
- Apache-2.0
- metadata
- { "cloudhal.area": "area:agent", "cloudhal.kind": "repo-skill", "cloudhal.status": "active" }
- description
- Add a Cloudhal capability (MCP tools + policy scopes + optional REST routes and Studio panel) in packages/mcp-server, packages/agent-runtime and apps/studio. Use when adding an integration or a new set of agent tools.
03 SKILL.md 正文
Add a capability
A capability is what an agent can do: MCP tools, the scopes they need, optional UI. A skill is how to do a job and never grants permission. Keep that boundary.
There is no separate capability package or manifest today (capabilities/ is still planned). A capability is added in the packages below; a significant one gets an RFC first (write-rfc).
Steps
- Tools. Add a module
packages/mcp-server/src/<area>-tools.tsexporting<area>Tools(): ToolDefinition[](seecommon.ts), or extend an existing one, and list it indefineTools()insrc/tools.ts. The order there is what agents see; updatetest/tool-order.test.ts. Each tool has JSON Schema input/output (built from the contract schemas where they exist; same generator-safe subset ascontract-change), honestannotations(readOnlyHint/destructiveHint/idempotentHint), itsscopes, and a handler overSiteGraphStoreor the package's store. Errors areToolErrors with stable codes and the next step in the text. - Scopes. Reuse an existing scope where it fits. A new one goes in
packages/agent-runtime/src/policy.ts:KEY_SCOPESif a key may carry it,PERSON_SCOPESif only people hold it, plus its implications (IMPLIES), then in the roles' sets insrc/roles.tsand, if agents should have it by default,defaultScopes. Scope names followarea:verb(content:write,site:publish), with an:ownvariant when it is limited to one's own nodes. - Approval. Anything that publishes, deletes or rolls back is
destructiveHint: trueorrequiresApproval: true, so the policy engine returnsapproval-requiredand the server asks a person (input_required; ADR-0014, ADR-0015 for modes). - REST and Studio (if people need it too). Routes in
packages/api(shared suite insrc/testing.ts), the typed client inapps/studio/src/lib/api/<area>.ts, and a screen or settings section built only from@cloudhal/ui(loadstudio-uiandkumo-design). Add the tool's label to Studio'stoolsmessages so Activity and Approvals name it. - Secrets are never committed (AGENTS.md rule 9); they come from the deployment's bindings and environment (
cloudhal deploy), with test values in.env.example. - Tests. A test file in
packages/mcp-server/test/that runs the tools throughrunTool(policy → audit → handler) on a fake or sqlite store, including a call outside the declared scopes being denied and an approval-gated call stopping for approval. - Docs. Run
node scripts/mcp-tools-doc.tsto regenerate the tool reference inpackages/mcp-server/README.md(pnpm checkfails when it is stale). If agents need a playbook for the job, add a skill underskills/official/.
References
docs/adr/0005-skills-format.md— capability vs skill boundarydocs/adr/0011-agent-layer.md,packages/mcp-server/README.mdpackages/agent-runtime/README.md— scopes and roles
04 同仓库更多 Skills
stale-review
Review a few published articles that have not been updated for a long time, make small safe fixes in drafts, and leave them as one proposed release for a person to schedule - never publishing anything. Built for a weekly scheduled agent task (begin_run, then end_run) that does not read visitor text. Use for a periodic content review or when asked which old articles need attention.
site-design
Design or redesign Cloudhal pages that look modern and follow the site's own design rules (DESIGN.md). Use when asked to build, design, restyle or improve a page, a landing page or a home page, or to write the site's design rules.
site-bootstrap
Set up a new Cloudhal site's first pages and navigation from a short brief. Use when a site is empty or the user asks to "set up", "scaffold" or "bootstrap" a site.
safe-edit
Make a reviewable change to an existing page or article - snapshot first, edit, preview, report the diff. Use for any edit request on existing content, including re-filing an article under other categories or tags.
rollback
Restore a site to an earlier snapshot after confirming the target with the user. Use when something published is wrong and the user asks to revert, undo or roll back.
publish-article
Check a draft article, file it under the site's categories and tags, produce a preview and submit it for publication now or at a set time, optionally under an embargo or with an expiry. Use when the user asks to publish, release, schedule or go live with an article.