skillhook

skillhook

Website: [skillhook.dev](https://skillhook.dev/?ref=readme)

Make your skills reactive. Webhook in, agent out. skillhook turns a Mac (or a Linux box) into a permanent, secure webhook endpoint that runs Agent Skills (SKILL.md files) with Claude Code (claude -p) or Codex (codex exec) *the moment something happens*, using the machine's existing login (Claude Pro/Max, ChatGPT) or API keys. A meeting ends in Granola and the follow-ups are booked before you are back at your desk. Sentry opens an issue and a fix branch is waiting for review. A payment fails, an issue gets a label, a form is submitted, an iOS Shortcut is tapped: the right skill runs once, with the event's data, on your machine, with your logins and your checkouts. Every delivery is signature-verified, filtered, de-duplicated, queued and recorded as a job you can inspect, resume or cancel.

Why not a scheduled task?

A scheduled task polls. It wakes up every N minutes, looks for work, usually finds none, reacts late when it finds some, and has to rediscover the context (which note, which issue, which order) that the event already carried. A webhook is the opposite. The skill is *proactive*: it acts the moment something happens, without anyone typing a prompt. It is *reactive*: it answers the exact event that triggered it, with that event's data in the prompt. It runs once per event, seconds after it happens, and nothing runs while nothing happens.

Give everything that has a trigger a webhook. Anything that can call a URL can start a skill: SaaS webhooks (Granola, Sentry, GitHub, Linear, Stripe, Slack, Standard Webhooks), Zapier and Make, iOS Shortcuts, curl, another agent. The work that has no trigger (a sweep of whatever is overdue, a weekday digest, a weekly report, a nightly clean-up) gets a schedule: on the same skill or hook, version-controlled next to the webhooks: skillhook fires it on time in the zone you name, catches up slots missed while the machine slept, and never runs one twice.

How it works

 Granola · Sentry · GitHub · Stripe · Slack · an iOS Shortcut · curl

│ HTTPS POST ▼ Tailscale Funnel https:// . .ts.net/hooks/ │ proxied to 127.0.0.1:8787 (the server never listens publicly) ▼ skillhook serve verify signature → de-duplicate (delivery id, identical in-flight payload) → filter (when) → queue │ ▼ claude -p / codex exec / a shell command in the skill's cwd, prompt = SKILL.md body + payload, unattended-run guardrails │ ▼ ~/.skillhook/jobs/ / job.json · payload.json · event.json · prompt.md · stdout.log · result.md · response.json

• A skill is a directory ~/.skillhook/skills/ /SKILL.md: standard Agent Skills frontmatter plus a skillhook: block that sets the runner, model, authentication, filters and working directory. Edits apply to the next delivery without a restart.
• A repository can carry its own hooks in a version-controlled skillhook.yaml (webhook name → a shell command, a SKILL.md in the repository, or inline instructions); skillhook link serves them. See Version-controlled hooks.
• Any skill or hook can also carry a schedule: (a cron expression, a time zone, and what to do about missed slots); the server fires it without a webhook. See Scheduled hooks.
• The runner is the real claude or codex CLI on the machine, so subscriptions, MCP servers, CLAUDE.md/AGENTS.md files and tool permissions apply as usual.
• Responses are immediate (202 with a job id) or synchronous with ?wait=N (or Prefer: wait=N); the agent's final message becomes the job result, and what it reports in response.json (completed, partial, needs_human, nothing_to_do, failed) becomes the job's outcome, so skillhook jobs list --outcome needs_human shows what is waiting for a person.
• Optional: skillhook cloud connect pairs the machine with Skillhook Cloud, a hosted dashboard for every machine's webhooks, jobs, questions waiting for a person, health and stats, with hosted webhook URLs that keep deliveries while the machine sleeps. Opt-in, outbound only, observe mode unless you choose control. With an organisation API key (skillhook cloud login), everything the dashboard shows and does works from the terminal (skillhook cloud overview, skillhook cloud ) and for your agent (the plugin's skillhook-cloud MCP server). skillhook cloud report sends the Skillhook team a problem report from a paired machine. See Skillhook Cloud and docs/cloud.md.
• The agent is not cut off while it runs: a per-run job API (MCP tools injected into the run, or skillhook job …) lets it report progress and ask a person a question; skillhook jobs answer "…" delivers the answer to the waiting agent or, when the run already ended, starts a new job that resumes the Claude or Codex session with it. See Reporting progress and asking a person.
• Developed against Claude Code 2.1.270, Codex CLI 0.153.4 and Tailscale 1.102.3. skillhook drives the CLIs through their headless flags (claude -p --output-format stream-json …, codex exec --json …; response: { mode: structured } adds claude --json-schema / codex --output-schema); skillhook run --dry-run shows the exact command line.

Quickstart

Requirements: Node 22 or newer; Claude Code logged in (claude login) and/or Codex logged in (codex login), or ANTHROPIC_API_KEY / OPENAI_API_KEY; Tailscale installed and signed in for the default public URL.

npm install -g @meterapp/skillhook

(npx @meterapp/skillhook works too; the command is skillhook either way. Had the unscoped skillhook 0.1.0 package installed? Run npm uninstall -g skillhook first: npm will not let a second package install the skillhook command. See Upgrading.)

skillhook init

Creates ~/.skillhook with skillhook.json, a .env (mode 600) holding a generated admin token and a bearer secret for the bundled hello skill, and skills/hello/SKILL.md.

skillhook doctor

Checks Node, config, secrets, skills, the Claude/Codex login, Tailscale, the server and the service, with a fix hint for each problem.

skillhook run hello --payload '{"name":"world"}'

Runs the skill in-process, no HTTP involved: the agent summarizes the payload, writes hello.md into the job directory and its final message is printed. Add --dry-run to see the runner command, environment and prompt instead of running.

skillhook service install

Installs a launchd LaunchAgent (macOS) or a systemd user unit (Linux) that runs skillhook serve at login and keeps it alive. skillhook serve runs it in the foreground instead.

skillhook expose tailscale

Runs tailscale funnel --bg --yes 8787, stores the resulting https:// . .ts.net as public_url and prints every skill's webhook URL. The first time, Tailscale asks for a one-time approval in its admin console; the command prints the link, approve and re-run.

skillhook send hello --wait 60

Signs a test payload the way the skill's auth expects, POSTs it to /hooks/hello on the running server and prints the job result. Add --public to go through the public URL.

Then create your own skill with skillhook skills new or copy an example with skillhook skills add sentry-triage, and give the URL from skillhook url plus the secret to the sender.

Skillhook Cloud

Skillhook Cloud is the hosted control plane for every skillhook machine, by the same team. Everything above works without it; it adds what one machine on its own cannot do:

• Hosted webhook URLs: a URL on the cloud that takes the delivery while the machine sleeps, is busy or has no public URL at all (no Tailscale needed to receive webhooks) and hands it over on the machine's next sync; the machine still verifies every signature with its own secret. Hosted URLs
• One dashboard of every machine's deliveries, jobs, health and stats. Every webhook of every machine stays on record with what became of it, rejected and skipped ones included, searchable by delivery id, machine, reason, path, sender address or time, and can be replayed from the dashboard, the API, the MCP server or the CLI: on the machine it arrived at, on another machine, or through another skill. Webhook history and replay
• An inbox of the questions agents ask people, with one-click choices; the pick resumes the agent's session.
• Alerts to Slack, a webhook or email when an agent needs a person, a job fails, a machine goes offline or a health check fails. Alerts
• Teams and roles (viewer, member, admin, owner) and an organisation API key for the whole fleet: skillhook cloud login, then skillhook cloud in a terminal and the plugin's skillhook-cloud MCP server for your agent. CLI, MCP
• Playbooks: worked setups for Sentry, Granola, GitHub issues, Intercom, Stripe disputes, leads, and webhook replay and testing, each with the prompt to paste into an agent and the full SKILL.md. Playbooks

Pair a machine with the code its dashboard shows (the pairing page prints the command, with --control when you choose control):

skillhook cloud connect --code XXXX-XXXX --url https://skillhook.dev

The link is opt-in and outbound only, in observe mode unless you choose control, and skillhook cloud disconnect ends it. The Free plan covers two machines; plans and limits: skillhook.dev/pricing. Docs: skillhook.dev/docs; the machine side (what leaves it, the commands the cloud may send, the kill switches) is docs/cloud.md.

Write a skill

A skill triggered by Sentry's issue webhooks, running Claude in a repository with a restricted tool set:

---

name: sentry-hotfix description: Investigates each newly created Sentry issue in the api repo. Ships a fix branch when the cause is clear, otherwise writes an escalation summary. Triggered by Sentry issue webhooks. skillhook: runner: claude model: opus effort: high cwd: ~/dev/api timeout_seconds: 1800 auth: type: sentry secret_env: SENTRY_CLIENT_SECRET when:

• header: sentry-hook-resource equals: issue
• path: action equals: created env: [SENTRY_AUTH_TOKEN, GH_TOKEN] claude: permission_mode: acceptEdits allowed_tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash(git:*)", "Bash(gh:*)", "Bash(pnpm test:*)"] max_budget_usd: 5

---

Sentry hotfix

A new issue was created in Sentry:

• {{payload.data.issue.shortId}}: {{payload.data.issue.title}}
• Level {{payload.data.issue.level}}, project {{payload.data.issue.project.slug}}
• Culprit: {{payload.data.issue.culprit}}