Skillhook Cloud from the terminal and the agent: the cloud's tools and the skillhook-cloud MCP server (0.7.0)

[JOsacky]

What

Everything the Skillhook Cloud dashboard shows and does, from the terminal and for an agent, with an organisation API key. The cloud now publishes its tools (GET /api/v1/tools: each with its JSON Schema and the scope it needs; MeterApp/skillhook-cloud#18), and skillhook builds its commands and MCP tools from that list at run time: a tool the cloud adds works here without a new skillhook, and no cloud tool is hand-written in this repo.

CLI

• skillhook cloud overview: what needs a person across the organisation (agents waiting with their question, open alerts, failing checks with the fix, failed jobs and rejected webhooks of 24 h, the day's numbers, next steps).
• skillhook cloud tools [tool]: what this key can do (and what a wider key would add); one tool's parameters.
• skillhook cloud <tool> [args] [--param value]…: any tool by name (answer_job <job> "yes" --option yes, run_skill mac-mini triage --payload @event.json --wait-seconds 120, get_stats --days 30, save_skill mac-mini triage --content-file SKILL.md, …). The words after the tool's name are read with its schema (before it, only skillhook's own options; a switch never swallows the next word, a text parameter takes it; --x=value, --no-x, --); required parameters as arguments in order, checked numbers, JSON as a literal, @file or -, --param-file for long text, --input for the whole input. skillhook's own options (--json, --help/-h, --version/-v, --dir) mean the same wherever they stand and are never a parameter's value, so --help never runs a tool and --answer=--help sends that text. Text output without control characters or bidirectional overrides (errors included), or --json (where they are \u escapes, for every command). A tool beyond the key's scope is refused before anything is sent.
• skillhook cloud secret <machine> <skill|NAME> [--force]: the machine generates a skill's secret (only a skill's: never its admin token or a runner's key) sealed to a one-time X25519 key pair here; only this terminal opens it, the cloud only forwards the sealed value.
• skillhook cloud login [--url URL] checks the key against the cloud named (else the one logged in to before, else the machine's; when those two differ it asks which) and keeps it bound to that cloud (SKILLHOOK_CLOUD_API_URL in .env): the key never goes anywhere else, whatever cloud.url says later, and login never touches the machine's link. The same key from the environment goes there too; a key kept by 0.6 goes to the machine's cloud until the next login, and cloud status says so. At a terminal it asks for the key without echo. cloud status / MCP cloud_status say whether a key is kept, for which cloud.
• skillhook's own tools do not move the link or the key for an agent: the local MCP server refuses cloud.* in update_config and SKILLHOOK_CLOUD_* in set_secret / generate_secret, and a skill's secret_env can no longer be SKILLHOOK_ADMIN_TOKEN or SKILLHOOK_CLOUD_* (the machine also refuses the cloud's secret.generate / secret.set for those, by whatever name they are asked for). An agent that runs commands on the machine acts with the person's rights all the same; the docs say so.

MCP and plugin

• skillhook mcp --cloud, registered by the plugin as skillhook-cloud next to skillhook: the cloud's tools (its names, descriptions, schemas and instructions), each call forwarded with the key and validated, authorised and audited by the cloud; plus generate_secret (sealed end to end). Without a key it offers only skillhook_cloud_setup, which says what is missing and loads the tools once the person logged in (tools/list_changed); the agent never handles the key.
• New plugin skill skillhook-cloud: start with describe_cloud, triage by failure kind, rejected deliveries and failing checks, act safely (confirm destructive actions, observe mode), set up machines, skills, secrets and hosted URLs.

Link

• After skill.put, skill.delete, config.patch and secret.* the next sync carries a fresh snapshot, so the dashboard (and list_skills) shows a saved skill and its secret at once instead of up to a minute later. The CLI also falls back to the machine's own answer (get_skill) for a skill saved a moment ago.

Release 0.7.0 (also carries #15, --help never runs a command). Docs: docs/cloud.md ("The whole organisation with an API key"), docs/mcp.md (the cloud server), README, llms.txt, AGENTS.md (layout, outbound requests), plugin manifests, CHANGELOG.

Review fixes (independent review of this PR)

The review found that an agent could use the local update_config tool to point cloud.url at another host and have the bridge send the organisation API key there. Fixed by binding the key to the cloud it was checked against and refusing cloud.* / SKILLHOOK_CLOUD_* changes from the local MCP. Also fixed: argument order around switches, --body needing a special case, control characters in keys and the overview, misleading "unknown subcommand" errors, one bad catalogue entry failing the whole catalogue (now skipped; a newer catalogue shape asks for an update), a catalogue tool being able to replace the local sealed generate_secret, and secret names beyond a skill's own.

Second review (of the fixes): flags before a tool's name were dropped (now read); skillhook's global parser and a tool's parser read --json/--help/-v differently (now reserved words for both); the docs overstated what keeps an agent from moving the key, and a skill naming SKILLHOOK_CLOUD_API_URL (or the admin token) as its secret_env could have it overwritten, also by the cloud through secret.set (now refused by the skill schema and by the resolved name on the machine); an environment key ignored the cloud kept with it and login forgot the previous cloud; a malformed catalogue schema could take the MCP bridge down (now skipped, and registration failures are contained); printable missed C1 controls, bidi overrides and error output.

Third review: a tool's switch before its name could swallow the name, and words before cloud never reached the tool (now: only skillhook's own options before the subcommand or tool, a usage error otherwise); --no-json/--no-help/--no-dir are skillhook's options too; login without --url could check a new key against a stale cloud (now it asks when the kept cloud and the machine's differ); --json output escapes C1 and bidi characters; cloud secret refuses the machine's own credentials even through a skill an older machine still has. Also: with cloud.upload_payloads false (or an organisation that keeps no bodies) the machine no longer sends a job's payload, event or prompt artifact.

Final review: -- is never a parameter's value and works again before the subcommand (skillhook cloud -- status); a blank --url is refused instead of skipping the two-clouds check, which now comes before the key is asked for; the withheld-body reason names both causes. The docs now say exactly what cloud.upload_payloads covers (a delivery's body and a job's payload, event and prompt): an agent's transcript and result are its own output and can quote what it read, and cloud.upload_artifacts: false keeps transcripts home.

Verification

• npm run check: typecheck, 303 tests (new src/cloud/tools.test.ts, src/cloud/bridge.test.ts, a CLI end-to-end test against the fake cloud's catalogue, the --help coverage lines for every new subcommand, and a link test that fails without the snapshot fix), build, schema, release metadata.
• End to end against the real Skillhook Cloud running locally with this build paired as a control-mode machine: login, overview, tools, run_skill, get_job_artifact, an agent's question answered with answer_job (delivered live), save_skill then cloud secret (decrypted only on the client), enable_hosted_url with a real webhook through it (accepted, run, via ingress), stats, audit log, and skillhook mcp --cloud over stdio (42 tools for an admin key; only skillhook_cloud_setup without a key). After the second review: cloud --machine e2e-mac list_jobs, --answer --json refused with the --answer=--json hint (nothing sent), -v printing the version, ESC and U+202E stripped from a cloud error, and cloud status for a bound and an unbound key. After the third: options before cloud or before a tool's name refused, login asking which cloud when two differ, --json carrying \u202e as an escape.

🤖 Generated with Claude Code