From 45d903f71fd660343aa8abcb8e039ef7f2afb820 Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Fri, 24 Jul 2026 08:47:32 +0200 Subject: [PATCH 1/2] chore: fix skill discovery warnings + document skills.sh install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skills.sh walker (npx skills add) discovers any file named SKILL.md under .claude/, .codex/, and docs/, then rejects the three repo-root copies because they lack YAML frontmatter — printing a "Skipped … missing required frontmatter" warning on every install. Those three files were stale, unmaintained duplicates of the canonical skills/deployhq/SKILL.md (already drifted from 8100 bytes down to 3302/4898). No code reads them — the installer embeds skills/deployhq via //go:embed — only one README line referenced them (and it also listed .cursor/SKILL.md and .windsurf/SKILL.md, which don't exist). - Delete .claude/SKILL.md, .codex/SKILL.md, docs/SKILL.md - Preserve the two agent-facing examples unique to docs/SKILL.md (`dhq api GET /account/capabilities` and `POST /beta/enrollments`) into skills/deployhq/references/launch.md so no content is lost - Point the README reference at the canonical skills/deployhq/SKILL.md - Add a skills.sh badge under the tagline - Add an "Install as an agent skill (skills.sh)" subsection Verified: `npx skills add deployhq/deployhq-cli` now reports "Found 1 skill" with zero frontmatter warnings. Canonical SKILL.md untouched; go build/vet/lint and skillinstaller+commands tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/SKILL.md | 111 ------------------ .codex/SKILL.md | 111 ------------------ README.md | 18 ++- docs/SKILL.md | 161 --------------------------- skills/deployhq/references/launch.md | 13 +++ 5 files changed, 29 insertions(+), 385 deletions(-) delete mode 100644 .claude/SKILL.md delete mode 100644 .codex/SKILL.md delete mode 100644 docs/SKILL.md diff --git a/.claude/SKILL.md b/.claude/SKILL.md deleted file mode 100644 index d0965aa..0000000 --- a/.claude/SKILL.md +++ /dev/null @@ -1,111 +0,0 @@ -# DeployHQ CLI — Agent Skill Guide - -## Identity -DeployHQ is a deployment automation platform. The `dhq` CLI manages projects, servers, and deployments. - -## Authentication -``` -# Guided setup (login or signup, pick a project) -dhq hello - -# Environment variables (CI/agents — no login needed) -export DEPLOYHQ_API_KEY=your-api-key -export DEPLOYHQ_ACCOUNT=your-account -export DEPLOYHQ_EMAIL=your-email - -# Or interactive login -dhq auth login -``` - -## Quick Reference - -### Discovery -``` -dhq commands --json # Full command catalog -dhq --help # Usage overview -dhq --help # Command details -``` - -### Common Workflows - -#### Deploy and wait for completion -``` -dhq deploy -p -s --wait --json -``` - -#### Deploy latest revision -``` -dhq deploy -p -s --use-latest --wait --json -``` - -#### Check deployment status -``` -dhq deployments show -p --json -``` - -#### Watch a deployment in real-time -``` -dhq deployments watch -p -``` - -#### View deployment logs -``` -dhq deployments logs -p -``` - -#### Rollback -``` -dhq rollback -p --json -``` - -#### Manage environment variables -``` -dhq env-vars list -p --json -dhq env-vars create --name KEY --value VALUE --locked -p -dhq global-env-vars create --name KEY --value VALUE -``` - -#### Escape hatch (any API endpoint) -``` -dhq api GET /projects//environment_variables -dhq api POST /projects//config_files --body '{"config_file":{...}}' -``` - -## Decision Tree - -### "Deploy code" -1. `dhq projects list --json` → find project -2. `dhq servers list -p --json` → find server -3. `dhq deploy -p -s --wait --json` → deploy and wait -4. On failure: `dhq deployments logs -p ` → read logs - -### "Check what's deployed" -1. `dhq deployments list -p --json` → recent deployments -2. `dhq deployments show -p --json` → details + steps - -### "Something went wrong" -1. `dhq deployments logs -p ` → read logs -2. `dhq rollback -p --json` → rollback if needed -3. `dhq deployments abort -p ` → abort if running - -### "Manage project config" -1. `dhq env-vars list -p --json` → environment variables -2. `dhq config-files list -p --json` → config files -3. `dhq build-commands list -p --json` → build pipeline -4. `dhq ssh-commands list -p --json` → SSH commands -5. `dhq servers list -p --json` → servers - -## Invariants -- Always use `--json` for machine-readable output -- JSON responses include `breadcrumbs` with suggested next commands -- Exit code 0 = success, 1 = failure (check JSON `ok` field for details) -- Empty results return exit 0 with empty `data` (not an error) -- `dhq api` covers any endpoint not in the command tree -- Use `--wait` on deploy to block until completion (exits non-zero on failure) - -## Triggers -- User mentions "deploy", "deployment", "release" → deployment workflow -- User mentions "server", "hosting" → server management -- User mentions "rollback", "revert" → rollback workflow -- User mentions "env var", "environment", "config" → configuration management -- User mentions "DeployHQ", "deployhq" → general CLI usage diff --git a/.codex/SKILL.md b/.codex/SKILL.md deleted file mode 100644 index d0965aa..0000000 --- a/.codex/SKILL.md +++ /dev/null @@ -1,111 +0,0 @@ -# DeployHQ CLI — Agent Skill Guide - -## Identity -DeployHQ is a deployment automation platform. The `dhq` CLI manages projects, servers, and deployments. - -## Authentication -``` -# Guided setup (login or signup, pick a project) -dhq hello - -# Environment variables (CI/agents — no login needed) -export DEPLOYHQ_API_KEY=your-api-key -export DEPLOYHQ_ACCOUNT=your-account -export DEPLOYHQ_EMAIL=your-email - -# Or interactive login -dhq auth login -``` - -## Quick Reference - -### Discovery -``` -dhq commands --json # Full command catalog -dhq --help # Usage overview -dhq --help # Command details -``` - -### Common Workflows - -#### Deploy and wait for completion -``` -dhq deploy -p -s --wait --json -``` - -#### Deploy latest revision -``` -dhq deploy -p -s --use-latest --wait --json -``` - -#### Check deployment status -``` -dhq deployments show -p --json -``` - -#### Watch a deployment in real-time -``` -dhq deployments watch -p -``` - -#### View deployment logs -``` -dhq deployments logs -p -``` - -#### Rollback -``` -dhq rollback -p --json -``` - -#### Manage environment variables -``` -dhq env-vars list -p --json -dhq env-vars create --name KEY --value VALUE --locked -p -dhq global-env-vars create --name KEY --value VALUE -``` - -#### Escape hatch (any API endpoint) -``` -dhq api GET /projects//environment_variables -dhq api POST /projects//config_files --body '{"config_file":{...}}' -``` - -## Decision Tree - -### "Deploy code" -1. `dhq projects list --json` → find project -2. `dhq servers list -p --json` → find server -3. `dhq deploy -p -s --wait --json` → deploy and wait -4. On failure: `dhq deployments logs -p ` → read logs - -### "Check what's deployed" -1. `dhq deployments list -p --json` → recent deployments -2. `dhq deployments show -p --json` → details + steps - -### "Something went wrong" -1. `dhq deployments logs -p ` → read logs -2. `dhq rollback -p --json` → rollback if needed -3. `dhq deployments abort -p ` → abort if running - -### "Manage project config" -1. `dhq env-vars list -p --json` → environment variables -2. `dhq config-files list -p --json` → config files -3. `dhq build-commands list -p --json` → build pipeline -4. `dhq ssh-commands list -p --json` → SSH commands -5. `dhq servers list -p --json` → servers - -## Invariants -- Always use `--json` for machine-readable output -- JSON responses include `breadcrumbs` with suggested next commands -- Exit code 0 = success, 1 = failure (check JSON `ok` field for details) -- Empty results return exit 0 with empty `data` (not an error) -- `dhq api` covers any endpoint not in the command tree -- Use `--wait` on deploy to block until completion (exits non-zero on failure) - -## Triggers -- User mentions "deploy", "deployment", "release" → deployment workflow -- User mentions "server", "hosting" → server management -- User mentions "rollback", "revert" → rollback workflow -- User mentions "env var", "environment", "config" → configuration management -- User mentions "DeployHQ", "deployhq" → general CLI usage diff --git a/README.md b/README.md index 3deb769..b044566 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ DeployHQ from your terminal -- for humans and agents. +[![Agent skill on skills.sh](https://skills.sh/b/deployhq/deployhq-cli)](https://skills.sh/deployhq/deployhq-cli) + ![dhq demo](assets/demo.gif) ## Install @@ -41,6 +43,18 @@ Download from [Releases](https://github.com/deployhq/deployhq-cli/releases) (Lin dhq update ``` +### Install as an agent skill (skills.sh) + +Add the DeployHQ skill to any supported AI agent (Claude Code, Cursor, Codex, +Gemini CLI, Copilot, and more) directly from this repo: + +```bash +npx skills add deployhq/deployhq-cli +``` + +(This is the cross-agent equivalent of `dhq skills install`, for users +discovering DeployHQ through the skills.sh directory.) + ## Quick Start ```bash @@ -332,8 +346,8 @@ dhq commands --json DEPLOYHQ_AGENT=my-bot dhq deploy -p my-app --json ``` -Standalone skill guides are also available at `.claude/SKILL.md`, -`.codex/SKILL.md`, `.cursor/SKILL.md`, `.windsurf/SKILL.md`, and `docs/SKILL.md`. +The canonical agent skill lives at [`skills/deployhq/SKILL.md`](skills/deployhq/SKILL.md) +and is what `dhq skills install` and `npx skills add deployhq/deployhq-cli` install. ### Non-Interactive Mode diff --git a/docs/SKILL.md b/docs/SKILL.md deleted file mode 100644 index dc7508f..0000000 --- a/docs/SKILL.md +++ /dev/null @@ -1,161 +0,0 @@ -# DeployHQ CLI — Agent Skill Guide - -## Identity -DeployHQ is a deployment automation platform. The `dhq` CLI manages projects, servers, and deployments. - -## Authentication -``` -# Guided setup (login or signup, pick a project) -dhq hello - -# Environment variables (CI/agents — no login needed) -export DEPLOYHQ_API_KEY=your-api-key -export DEPLOYHQ_ACCOUNT=your-account -export DEPLOYHQ_EMAIL=your-email - -# Or interactive login -dhq auth login -``` - -## Quick Reference - -### Discovery -``` -dhq commands --json # Full command catalog -dhq --help # Usage overview -dhq --help # Command details -``` - -### Common Workflows - -#### Deploy and wait for completion -``` -dhq deploy -p -s --wait --json -``` - -#### Deploy latest revision -``` -dhq deploy -p -s --use-latest --wait --json -``` - -#### Check deployment status -``` -dhq deployments show -p --json -``` - -#### Watch a deployment in real-time -``` -dhq deployments watch -p -``` - -#### View deployment logs -``` -dhq deployments logs -p -``` - -#### Rollback -``` -dhq rollback -p --json -``` - -#### Manage environment variables -``` -dhq env-vars list -p --json -dhq env-vars create --name KEY --value VALUE --locked -p -dhq global-env-vars create --name KEY --value VALUE -``` - -#### Test repository and server connectivity -``` -dhq test-access -p --json -dhq test-access -p --server --json -``` - -#### Escape hatch (any API endpoint) -``` -dhq api GET /projects//environment_variables -dhq api POST /projects//config_files --body '{"config_file":{...}}' -``` - -## Decision Tree - -### "Deploy code" -1. `dhq projects list --json` → find project -2. `dhq servers list -p --json` → find server -3. `dhq deploy -p -s --wait --json` → deploy and wait -4. On failure: `dhq deployments logs -p ` → read logs - -### "Check what's deployed" -1. `dhq deployments list -p --json` → recent deployments -2. `dhq deployments show -p --json` → details + steps - -### "Something went wrong" -1. `dhq deployments logs -p ` → read logs -2. `dhq rollback -p --json` → rollback if needed -3. `dhq deployments abort -p ` → abort if running - -### "Test connectivity" -1. `dhq test-access -p --json` → test all servers + repo -2. `dhq test-access -p --server --json` → test single server - -### "Manage project config" -1. `dhq env-vars list -p --json` → environment variables -2. `dhq config-files list -p --json` → config files -3. `dhq build-commands list -p --json` → build pipeline -4. `dhq ssh-commands list -p --json` → SSH commands -5. `dhq deployment-checks list -p --json` → pre_build / post_deploy gates -6. `dhq servers list -p --json` → servers - -### "Check account beta/managed-offerings eligibility" -``` -dhq api GET /account/capabilities --json -``` -Returns `beta_features`, `static_hosting_eligible`, `managed_vps_eligible`. - -### "Enable managed-resources beta from CLI" -``` -dhq api POST /beta/enrollments --body '{"protocol":"static_hosting"}' -``` -Admin required for first enrollment; already-enrolled accounts are idempotent. - -### "List Managed VPS regions and sizes" -``` -dhq api GET /managed_hosting/regions --json -dhq api GET /managed_hosting/sizes --json -``` -Requires beta_features enabled. - -### "Create a Static Hosting server" -``` -dhq servers create -p --name "My Site" --protocol-type static_hosting \ - --subdomain --subdirectory dist --json -``` - -### "Create a Managed VPS server" -``` -dhq servers create -p --name "My VPS" --protocol-type managed_vps \ - --region lon1 --size s-1vcpu-1gb --json -``` - -### "Poll provisioning status" -``` -dhq servers show -p --json -``` -Check `provisioning_status` ("provisioning" / "active" / "error"), `ip_address` (VPS), -and `static_hosting.url` (static) in the response. - -## Invariants -- Always use `--json` for machine-readable output -- JSON responses include `breadcrumbs` with suggested next commands -- Exit code 0 = success, 1 = failure (check JSON `ok` field for details) -- Empty results return exit 0 with empty `data` (not an error) -- `dhq api` covers any endpoint not in the command tree -- Use `--wait` on deploy to block until completion (exits non-zero on failure) - -## Triggers -- User mentions "deploy", "deployment", "release" → deployment workflow -- User mentions "server", "hosting" → server management -- User mentions "rollback", "revert" → rollback workflow -- User mentions "env var", "environment", "config" → configuration management -- User mentions "test", "connectivity", "access" → test-access workflow -- User mentions "DeployHQ", "deployhq" → general CLI usage diff --git a/skills/deployhq/references/launch.md b/skills/deployhq/references/launch.md index 8518a96..c62bc2f 100644 --- a/skills/deployhq/references/launch.md +++ b/skills/deployhq/references/launch.md @@ -75,3 +75,16 @@ On failure the error carries a stable `reason`, a `retryable` boolean, and a `ne - **Rollback:** both targets roll back the same way — `dhq rollback ` redeploys the previous revision through the same pipeline (`dhq deployments list` shows history). There's no separate static-vs-VPS rollback command. - Managed VPS and Static Hosting require the **managed-resources beta**. `launch` enrolls the account automatically when an admin runs it (the enrollment endpoint is idempotent and admin-gated); non-admins get `beta_enroll_required`. - **Pricing during beta:** Managed VPS and Static Hosting are free for early customers while in beta; the listed monthly rate applies once the beta ends. The CLI's runtime copy is gated by a single switch (`meteredResourcesInBeta` in `internal/commands/metered.go`) — flip it when the resources go GA, and update this beta wording in the same change. + +### Checking eligibility & enrolling manually (escape hatch) + +`launch` handles enrollment automatically, but an agent can inspect or drive it directly via `dhq api`: + +``` +# Am I eligible? Returns beta_features, static_hosting_eligible, managed_vps_eligible. +dhq api GET /account/capabilities --json + +# Enable the managed-resources beta (admin required for the first enrollment; +# already-enrolled accounts are idempotent). +dhq api POST /beta/enrollments --body '{"protocol":"static_hosting"}' +``` From 9c8c15ff4871ece17462d0e6615a28da82396e7d Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Fri, 24 Jul 2026 09:04:53 +0200 Subject: [PATCH 2/2] fix(skill): correct capability check to GET /profile, add fence language Address CodeRabbit review on #37: - The ported example used `dhq api GET /account/capabilities`, which is not a real endpoint. The SDK's GetAccountCapabilities reads the flags from the `account` sub-object of GET /profile (pkg/sdk/managed_hosting.go:19-24), so the documented escape hatch would have 404'd. Corrected to GET /profile and noted the flags live under `account.*`. - Tag the fenced example `bash` (matches launch.md:14). Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/deployhq/references/launch.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/skills/deployhq/references/launch.md b/skills/deployhq/references/launch.md index c62bc2f..e023f4d 100644 --- a/skills/deployhq/references/launch.md +++ b/skills/deployhq/references/launch.md @@ -80,9 +80,11 @@ On failure the error carries a stable `reason`, a `retryable` boolean, and a `ne `launch` handles enrollment automatically, but an agent can inspect or drive it directly via `dhq api`: -``` -# Am I eligible? Returns beta_features, static_hosting_eligible, managed_vps_eligible. -dhq api GET /account/capabilities --json +```bash +# Am I eligible? The flags live on the `account` sub-object of the profile +# response: account.beta_features, account.static_hosting_eligible, +# account.managed_vps_eligible. +dhq api GET /profile --json # Enable the managed-resources beta (admin required for the first enrollment; # already-enrolled accounts are idempotent).