AGENT SKILL

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

  1. Tools. Add a module packages/mcp-server/src/<area>-tools.ts exporting <area>Tools(): ToolDefinition[] (see common.ts), or extend an existing one, and list it in defineTools() in src/tools.ts. The order there is what agents see; update test/tool-order.test.ts. Each tool has JSON Schema input/output (built from the contract schemas where they exist; same generator-safe subset as contract-change), honest annotations (readOnlyHint/destructiveHint/idempotentHint), its scopes, and a handler over SiteGraphStore or the package's store. Errors are ToolErrors with stable codes and the next step in the text.
  2. Scopes. Reuse an existing scope where it fits. A new one goes in packages/agent-runtime/src/policy.ts: KEY_SCOPES if a key may carry it, PERSON_SCOPES if only people hold it, plus its implications (IMPLIES), then in the roles' sets in src/roles.ts and, if agents should have it by default, defaultScopes. Scope names follow area:verb (content:write, site:publish), with an :own variant when it is limited to one's own nodes.
  3. Approval. Anything that publishes, deletes or rolls back is destructiveHint: true or requiresApproval: true, so the policy engine returns approval-required and the server asks a person (input_required; ADR-0014, ADR-0015 for modes).
  4. REST and Studio (if people need it too). Routes in packages/api (shared suite in src/testing.ts), the typed client in apps/studio/src/lib/api/<area>.ts, and a screen or settings section built only from @cloudhal/ui (load studio-ui and kumo-design). Add the tool's label to Studio's tools messages so Activity and Approvals name it.
  5. 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.
  6. Tests. A test file in packages/mcp-server/test/ that runs the tools through runTool (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.
  7. Docs. Run node scripts/mcp-tools-doc.ts to regenerate the tool reference in packages/mcp-server/README.md (pnpm check fails when it is stale). If agents need a playbook for the job, add a skill under skills/official/.

References

  • docs/adr/0005-skills-format.md — capability vs skill boundary
  • docs/adr/0011-agent-layer.md, packages/mcp-server/README.md
  • packages/agent-runtime/README.md — scopes and roles

04 同仓库更多 Skills

cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1
cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1
cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1
cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1
cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1
cloudhal-dev
cloudhal-dev/cloudhal

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.

★ 1