skillhook

Copies a bundled example into <home>/skills (optionally under another name) and generates its secret when skillhook manages it.

A person's answer to a job that is waiting: delivered live to the agent's pending job_ask_human call when the job is still running (`delivered: live`); otherwise recorded and, unless resume is `never`, a new job with trigger `resume` continues the agent's session with it (`claude --resume` / `codex exec resume`; `delivered: resumed`, `resume_job_id`). Use list_jobs with waiting: true to find such jobs; pass `option` when the person picked one of the question's options, `options` for the picks of a multiple-choice question (the answer then lists them one per line), `by` to say who answered.

Cancels a queued or running job on the running server.

Ask the npm registry for the newest skillhook (what `skillhook update` does). With `install: true` and a newer version, upgrade with the package manager that installed skillhook and restart the background service when it has no jobs in progress; a busy service keeps running the old version until `restart_server`.

Stops the link to Skillhook Cloud: sets cloud.enabled to false, revokes and removes the machine token and key, deletes the local spool, and tells a running server (which stops syncing within seconds). Nothing leaves the machine afterwards. keep_token keeps the token in .env for a later reconnect.

Sends a problem report to the Skillhook team through Skillhook Cloud, from this paired machine (what `skillhook cloud report` does). Use it only when the person asked to report something, and tell them what goes out (dry_run: true returns exactly that without sending): the title and body (write them from what the person said), optional kind, severity, contact_email and the job id, delivery id or skill it is about, and unless diagnostics is false the machine's facts: skillhook, Node and OS versions, cloud mode, the link's state, whether each runner is ready and the failing or warning health checks, all scrubbed of every .env value. Never payloads, logs, prompts or job output. Returns the issue number and URL and whether a confirmation email went out. Fails on a machine that is not paired (`skillhook cloud connect`) or under SKILLHOOK_NO_CLOUD.

Whether this machine is paired with Skillhook Cloud (the opt-in dashboard for every machine's webhooks, jobs and health), its URL, machine id and mode (observe: the cloud can look; control: it can also run skills and change the configuration), whether the token is present (never the token itself), the running server's link state (connected, degraded, disconnected with the reason, last sync, events waiting) and whether an organisation API key is kept here for the fleet (api_key; the skillhook-cloud MCP server and `skillhook cloud overview` use it). Pairing is not a tool on purpose: the person runs `skillhook cloud connect --code <code from their dashboard>` in a terminal, so a code from an untrusted source can never hand this machine to someone else's account.

Creates <home>/skills/<name>/SKILL.md. Writes the instructions (markdown body) and the skillhook frontmatter (runner, model, auth, filters). For bearer/basic/hmac auth a secret is generated and returned once; for provider-signed auth (github, sentry, granola, stripe, slack, linear, svix, standard-webhooks) call set_secret with the provider's signing secret afterwards.

Checks Node, config, secrets, skills, Claude/Codex login, Tailscale exposure, server and service.

mode=funnel: public HTTPS URL (internet). mode=serve: tailnet-only URL. mode=off: disable. mode=status: current exposure. The URL is permanent (your Tailscale node name) and survives reboots.

Generates a random secret for a skill (or "admin") and returns it once. Existing secrets are kept unless force=true.

The effective skillhook.json (defaults applied), which keys the running server applies live (`hot_keys`) and which need a restart (`restart_keys`: host, port), and what is pending a restart. From the running server when there is one.

One delivery record; `include_body` adds the request body when the log kept it (rejected and filtered deliveries) or the payload of the job an accepted delivery created.

Everything doctor checks plus, with deep (default), every MCP server Claude Code and Codex know (connected, needs authentication, failed), installed plugins, `codex doctor`, disk space and each skill's last run, grouped (system, skillhook, runners, tools, skills, exposure). Through the running server's cached report when there is one (`refresh` probes again); otherwise probed now.

Job record plus optional artifacts (result, response, prompt, stdout, stderr, payload, event) and, when the agent reported any, its progress timeline, pending question and answer.

Is each runner (claude, codex, shell) installed and logged in, or given an API key: what every job checks before it starts (a `fallback:` runner takes over, or the job fails fast with failure.kind auth). Through the running server's cached answer when there is one (`refresh` probes again).

Returns a skill's summary and the full SKILL.md content.

Numbers over the jobs and deliveries on this machine: jobs by status, outcome, trigger, runner and failure kind, success and completion rates, duration and queue-wait percentiles, cost and tokens, deliveries by outcome and HTTP status, and the same per skill. `since` takes 24h, 7d, 2w or an ISO-8601 instant.

Webhook URL per skill, using the public URL (Tailscale/config) when one exists.

Registers a repository's skillhook.yaml (dir, or the YAML file itself) in skillhook.json so its hooks are served at /hooks/<name>; the running server picks them up without a restart. With init=true a starter skillhook.yaml is written first when none exists (a `run: git pull --ff-only` hook for merged GitHub pull requests). Secrets skillhook manages (bearer/basic/hmac) are generated and returned once; provider-signed hooks need set_secret afterwards.

The Claude Code and Codex accounts (named logins) skills run as: for each its state (ready, needs_login, expired, limited, missing_secret, disabled), who it is logged in as, its plan, its usage windows (5h, weekly, per model; with `usage: true` asked from each account's CLI now), its last use, its jobs of the last 24 hours, the skills that use it, and `attention`: what needs a person, each with the command that fixes it. With `mcp: true` (slow: every server connects) also `mcp`: the MCP servers, claude.ai / ChatGPT connectors and plugins each account's runs get, whether each connected, needs authentication or failed, and attention items for them. Logging in is done by a person in a terminal (`skillhook accounts login <name>`), never by a tool.

Every request to /hooks/<skill> the server received, newest first, with its outcome: accepted (a job was created), duplicate, in_flight, skipped (a when filter), rejected (401, 404, 413, 503, …), challenge, error. Use it to see why a webhook did not run. `after` pages further back.

Bundled example skills (hello, granola-meeting-actions, sentry-triage, …) that add_example can copy.

Recent jobs, newest first. `status` is how the process ended, `outcome` whether the task was done. `waiting: true` lists only the jobs waiting for a person (an unanswered question, or outcome needs_human not yet resumed): answer them with answer_job. `after` (the `next_after` of the previous call) pages further back; `since` is an ISO-8601 instant.

Repositories whose skillhook.yaml is served by this machine: directory, file, and each hook with its runner, kind (run/skill/prompt), auth, cwd and webhook URL. This is the version-controlled answer to 'which skill runs from which webhook'.

Every skill or hook with a `schedule:`: cron, time zone, catch_up and overlap policy, whether it is enabled and also has a webhook, the next due time, and the last slot, job and status (live from the running server when there is one). A hook with `webhook: false` runs only on its schedule.

Names of secrets in <home>/.env (values are never returned).

Lists every skill with runner, model, auth type, whether its secret is configured, and its webhook URL.

Runs a recorded delivery again through the skill as it is now, as a new job with trigger `replay`: the original payload, headers and query, no signature check, `when` filters applied unless skip_filters, identical in-flight work is reused when deduplication is enabled on the running server. A delivery that was rejected needs `force` (its body was never verified). Uses the running server when there is one, otherwise runs in-process.

Runs the request an earlier job received again, as a new job with trigger `replay` and `replay_of` pointing at the original (same payload, headers and query; `when` filters applied unless skip_filters; runner/model/effort may be overridden).

Ask the running server to restart: it pauses dispatch while keeping intake and cloud sync available, lets running jobs finish for up to wait_seconds (default 30), then exits only if idle. On timeout it resumes dispatch without terminating jobs; `force: true` terminates them. Launchd / systemd starts it again after an exit. Only works for a server run as the service (409 otherwise); use it after update_config changed host or port, or after an update was installed.

Runs a skill with a payload through the same prompt, runner and job pipeline as a webhook, skipping HTTP auth, the skill's when filters and de-duplication. Uses the running server when there is one (job visible in its queue), otherwise runs in-process. Set wait_seconds to block for the result; otherwise poll get_job. Use send_test_webhook to exercise auth and filters too.

Signs a payload the way the skill's auth expects and POSTs it to /hooks/<name>, proving the HTTP path (auth, filters, queue) works. Defaults to the local server; set public=true to go through the public URL.

install: run the server at login (launchd/systemd) and keep it alive. status/restart/uninstall/logs.

Stores a secret in <home>/.env (mode 600). `name` is an ENV_VAR_NAME, a skill name (its secret_env) or "admin". Use it for provider signing secrets (Granola whsec_…, Sentry client secret, GitHub webhook secret) and for API keys a skill needs via `env:`.

Overview: home directory, server state, public URL, skills and recent jobs. Call this first.

Runs the complete text of a SKILL.md (frontmatter included) with a payload, exactly like run_skill, without installing it: the file is kept in the job directory (jobs/<id>/skill/<name>/SKILL.md) and the job has trigger `test`. Use it to try a draft before create_skill, or to see how a change would behave. Through the running server when there is one, otherwise in-process.

Stops serving a repository's hooks (they answer 404 at once). The repository and its skillhook.yaml are not touched.

Change skillhook.json: `set` maps dotted keys to values ({"concurrency": 3, "defaults.model": "sonnet"}), `unset` lists dotted keys to remove. One validated write; an invalid result changes nothing. The running server re-reads the file at once and says which keys it applied live and which (host, port) wait for a restart (`restart_server`).

Replaces a skill's SKILL.md with new content after validating the frontmatter.

Parses every SKILL.md (or one) and reports errors and missing secrets.