kayforkind/skill-slice/aiq-deploy

Claude Code and agent skill by kayforkind/skill-slice

Trust tier 3
  • community
  • ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]
Source check pending

Checking that the SKILL.md file is still in the repository.

Deploys, validates, troubleshoots, and stops NVIDIA AI-Q Blueprint 2.1.x (Docker Compose, Kubernetes/Helm, local process, CLI, or web UI). Use when installing or cloning AI-Q, starting the backend, checking /health, fixing port or credential failures, or handing a verified AIQ_SERVER_URL to aiq-research. Not for deep research report generation (that is aiq-research).

Install

npx vskill@latest install kayforkind/skill-slice/aiq-deploy

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

The same SKILL.md was published earlier as kayforkind/skill-slice/aiq-deploy.

AIQ Deploy Skill

Overview

This skill owns setup, deployment, operational checks, troubleshooting, and shutdown of the NVIDIA AI-Q Blueprint server. It does not run deep research itself. After deployment is healthy, hand off the verified server URL to aiq-research.

The workflow stays explicit so deployment validation and handoff are repeatable across supported agent clients.

Version Compatibility: This skill targets NVIDIA AI-Q Blueprint version 2.1.0.

text
Skill version: X.Y.Z
Blueprint version: A.B.C
Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)
  • Skill 2.1.0 ↔ Blueprint 2.1.0 ✅
  • Skill 2.1.0 ↔ Blueprint 2.2.0 ✅
  • Skill 2.1.0 ↔ Blueprint 2.1.5 ✅
  • Skill 2.1.0 ↔ Blueprint 3.0.0 ❌
  • Skill 2.1.0 ↔ Blueprint 2.0.0 ❌

If the Blueprint version is not compatible, check for an updated skill, use a compatible Blueprint version, or proceed only when the user accepts the risk.

When to Use

Use this skill when the user asks to:

  • Install or clone the NVIDIA AI-Q Blueprint repository.
  • Deploy or run AI-Q locally or on a cluster (Docker Compose, Kubernetes/Helm, local process, CLI, or browser UI).
  • Validate that the AI-Q backend is healthy and ready for aiq-research.
  • Troubleshoot deployment issues: port conflicts, missing credentials, unhealthy services, config failures.
  • Stop, restart, rebuild, or clean up AI-Q services.
  • Hand off a verified AIQ_SERVER_URL to aiq-research.

Do not use this skill for deep research report generation — that belongs to aiq-research.

Prerequisites

  • Access to clone or update https://github.com/NVIDIA-AI-Blueprints/aiq.
  • Git available in the shell.
  • One deployment runtime:
  • Docker Engine with Docker Compose v2 — default durable local deployment.
  • Python 3.11+ and `uv` — local process or CLI mode.
  • Node.js 20+ and `npm` — local browser UI development mode.
  • `kubectl` 1.28+, Helm 3.12+, and cluster access — Kubernetes/Helm mode.
  • Network access to GitHub, NVIDIA-hosted model endpoints, and any selected search provider.
  • Credentials stored outside chat. Hosted-model usage requires NVIDIA_API_KEY; web research requires at least one supported search provider key: TAVILY_API_KEY, SERPER_API_KEY, or EXA_API_KEY.
  • System capacity for the selected runtime. Docker Compose mode starts the AI-Q backend and PostgreSQL by default; browser UI mode also uses frontend port 3000. Self-hosted model or RAG deployments may require GPU resources.
Windows host (PowerShell) note: Commands shown in bash syntax work in Git Bash or WSL. In PowerShell, replace test -f with Test-Path, cp with Copy-Item, and export VAR=... with $env:VAR = "...". Use curl.exe (not the curl alias to Invoke-WebRequest) for health checks.

Procedure

Step 1 — Locate or clone AI-Q

When to load: If no AI-Q checkout exists or the user asks to install/clone AI-Q, read references/locate-or-clone.md before cloning.

In an existing checkout, confirm the required files:

bash
pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs

Expected output: pwd prints the AI-Q repository path; the test commands exit with status 0 and produce no output.

PowerShell equivalent:

powershell
Get-Location
Test-Path pyproject.toml
Test-Path deploy/.env.example
Test-Path configs
Step 2 — Select the deployment mode

If the user asks to install, deploy, set up, or run AI-Q without naming a mode, ask:

text
How do you want to run AI-Q?
1. Skill backend - backend-only service for aiq-research w/o browser UI.
2. CLI - interactive terminal AI-Q.
3. UI - browser AI-Q app with backend and frontend.
4. Custom - choose an existing AI-Q config or review advanced customization docs before deployment.

Wait for the user's answer before starting services.

Do not ask this question when:

  • The user already specified a mode (Docker Compose, Helm, UI, CLI, or Agent Skill backend).
  • aiq-research routed here because a deep research request needs a backend. In that case, prefer Agent Skill backend and ask only for permission to start it if needed.
Step 3 — Prepare environment and secrets

When to load: Read references/env-and-secrets.md before changing deploy/.env.

bash
if [ ! -f deploy/.env ]; then
cp deploy/.env.example deploy/.env
echo "created deploy/.env from deploy/.env.example"
fi

Expected output when the file is missing: created deploy/.env from deploy/.env.example Expected output when the file exists: no output; the existing file is preserved.

Before writing secrets, verify deploy/.env is git-ignored:

bash
git check-ignore deploy/.env

Expected output: deploy/.env or a matching ignore rule. If it is not ignored, stop and fix the ignore rule before placing credentials in the file.

HARD RULES:

  • Never print secret values. Check only whether required environment variables are set.
  • Never overwrite `deploy/.env` when it already exists.
  • Never ask the user to paste secret values into chat. Ask them to update deploy/.env directly.
Step 4 — Route to the selected deployment path

Match the user request, then read the referenced file before acting:

User IntentReference to Load
No AI-Q checkout exists, install AIQ, clone AIQ, locate reporeferences/locate-or-clone.md
Configure environment, check API keys, inspect .envreferences/env-and-secrets.md
Choose an AI-Q workflow config, understand config files, set BACKEND_CONFIG or CONFIG_FILEreferences/configs.md
Backend-only local server for aiq-research, AIQ as an Agent Skillreferences/skill-backend.md
Terminal assistant, CLI-only run, no web UIreferences/terminal-cli.md
Quick local development run, start UI/backend without containersreferences/local-web.md
Default durable local deployment, Docker Compose, containers, PostgreSQLreferences/docker-compose.md
Kubernetes, Helm, cluster deploymentreferences/kubernetes-helm.md
Foundational RAG / FRAG integrationreferences/frag.md
Basic health checks, shallow smoke checks, handoff to aiq-researchreferences/validation.md
Optional deep research completion validationreferences/end-to-end-validation.md
Logs, unhealthy services, port conflicts, config failuresreferences/troubleshooting.md
Stop services, restart, rebuild, safe cleanupreferences/shutdown.md
Step 5 — Validate and hand off

When to load: After startup, read references/validation.md and run the appropriate checks for the selected mode.

For the default local backend, verify health:

bash
curl -sf http://localhost:8000/health

Expected output: a successful JSON health response or an empty successful response depending on the server build. If the command fails, read references/troubleshooting.md and diagnose before claiming the backend is ready.

aiq-research needs a reachable AI-Q server URL. If the backend is on the default port:

bash
AIQ_SERVER_URL=http://localhost:8000

If the backend runs elsewhere:

bash
export AIQ_SERVER_URL="http://localhost:<PORT>"

PowerShell:

powershell
$env:AIQ_SERVER_URL = "http://localhost:8000"

HARD RULE: Do not continue into deep research or deep research completion validation unless the user asks for it or confirms the post-deploy validation prompt. This skill's success criterion is a deployed and basically validated server, not report generation quality.

Examples

Example 1: Deploy a backend-only Skill server with Docker Compose
bash
test -f deploy/.env || cp deploy/.env.example deploy/.env
git check-ignore deploy/.env
cd deploy/compose
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml config --quiet
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml up -d --build aiq-agent
curl -sf http://localhost:8000/health

Expected output:

text
deploy/.env
<docker compose starts aiq-agent and dependencies>
<health endpoint returns a successful response>

If Docker, ports, credentials, or health checks fail, read references/troubleshooting.md before retrying.

Example 2: Hand off a non-default backend URL to aiq-research
bash
export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"

Expected output: a successful health response. Then tell the user to keep AIQ_SERVER_URL set before invoking aiq-research.

Pitfalls

Backend port is already in use

Symptoms: Docker Compose fails to bind port 8000; curl -sf http://localhost:8000/health reaches an unexpected service or fails.

Causes: Another AI-Q backend or local dev server is running; PORT in deploy/.env conflicts.

Solutions:

  1. Identify the process:

``bash lsof -nP -iTCP:8000 -sTCP:LISTEN ``

  1. Either stop the conflicting process with the user's approval or set a different port in deploy/.env (e.g., PORT=8100).
  2. Restart and verify:

``bash curl -sf http://localhost:8100/health ``

Required credentials are missing

Symptoms: Infrastructure starts, but model-backed chat or research requests fail. Logs mention unauthorized, forbidden, invalid key, or missing provider configuration.

Causes: NVIDIA_API_KEY is missing or empty; no supported search provider key is configured.

Solutions:

  1. Check presence without printing values by following references/env-and-secrets.md.
  2. Ask the user to update deploy/.env; do not ask them to paste secrets into chat.
  3. Rerun references/validation.md after the user updates credentials.
Backend is healthy but not compatible with aiq-research

Symptoms: /health succeeds, but /chat or /v1/jobs/async/agents fails. aiq-research reports async agents unavailable.

Causes: The selected config is CLI-only or does not expose the web/API backend expected by the skill. BACKEND_CONFIG or CONFIG_FILE points at the wrong AI-Q config.

Solutions:

  1. Read references/configs.md and confirm the selected config is API-enabled.
  2. For the default Skill backend, use configs/config_web_default_llamaindex.yml.
  3. Restart the backend and rerun references/validation.md.
Docker cleanup would remove useful state

Symptoms: Troubleshooting suggests docker compose down -v; the user may have local PostgreSQL job or checkpoint data they want to keep.

Causes: down -v removes Docker volumes. Rebuilds and restarts are often enough for config or image changes.

Solutions:

  1. Prefer a normal restart from references/shutdown.md.
  2. Ask for explicit approval before running volume deletion.
  3. After cleanup, rerun deployment and validation from the selected route.
FRAG not ready

HARD RULE: Do not claim FRAG is ready unless both RAG_SERVER_URL and RAG_INGEST_URL are configured and reachable. Read references/frag.md for setup details.

Verification

Run these checks after the selected deployment path starts:

  1. Health endpoint (default port 8000):

``bash curl -sf http://localhost:8000/health `` Expected: successful JSON or empty 200 response.

  1. Non-default port (if applicable):

``bash curl -sf "$AIQ_SERVER_URL/health" `` Expected: successful health response.

  1. Git ignore check (should already be done before secrets):

``bash git check-ignore deploy/.env ` Expected: deploy/.env` or matching ignore rule.

  1. Repository file check (in existing checkout):

``bash test -f pyproject.toml && test -f deploy/.env.example && test -d configs && echo "OK" ` Expected: OK`

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
5

Not refreshed yet.

Extension points

  • hookPre/post lifecycle hooks

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kayforkind/skill-slice/aiq-deploy/badge)](https://verified-skill.com/skills/kayforkind/skill-slice/aiq-deploy)

Something wrong with this skill or its page? Tell us.