Skill Support CLI

Agent-first CLI for the Skill Recordings customer support platform. Powers triage, conversation management, health checks, evals, and pipeline debugging across Total TypeScript, Pro Tailwind, Epic Web, and other properties.

Repo: skillrecordings/support (private) Binary: ~/.local/bin/skill All commands return JSON with --json or --format json.

Quick Start (new developer)

Three commands. Needs: GitHub account in skillrecordings org.

# 1. Install binary
curl -fsSL https://raw.githubusercontent.com/skillrecordings/support/main/packages/cli/install.sh | bash

# 2. Authenticate (opens browser)
skill auth setup

# 3. Verify
skill doctor

No 1Password CLI needed. Auth uses GitHub device flow → broker verifies org membership → secrets delivered encrypted, held in memory only.

When Things Go Wrong

Always start with skill doctor. It checks every dependency and gives specific fix instructions.

skill doctor --json

Common Failures

Symptom	Fix
`Missing Bearer token`	Session expired → `skill auth setup`
`ENOENT .env.encrypted`	Binary missing embedded env → reinstall: `curl -fsSL ... \| bash`
`Connection refused` on Front API	Check `FRONT_API_TOKEN` → `skill auth status --json`
`skill: command not found`	Add to PATH: `export PATH="$HOME/.local/bin:$PATH"`
Stale data / wrong property	Check which app: `skill health --list --json`
`SKIP_ENV_VALIDATION` in output	No secrets loaded → `skill auth setup`

Auth Debugging

# Check what auth provider is active
skill auth status --json

# Re-authenticate (clears session, starts fresh device flow)
skill auth setup

# Legacy 1Password path (admin only)
skill auth setup --legacy
skill auth login --token "$OP_SERVICE_ACCOUNT_TOKEN"
skill auth whoami --json

Secret Resolution Order

OAuth Broker (default) → GitHub device flow → encrypted delivery → memory only
1Password (admin)      → OP_SERVICE_ACCOUNT_TOKEN → vault lookup
.env.encrypted (CI)    → SKILL_AGE_KEY → decrypt
.env.local (dev)       → plaintext fallback

Commands Reference

Triage Workflow (most common)

# See what needs attention
skill front inbox --limit 20 --json

# Triage a specific inbox
skill front triage <inbox-id> --limit 20 --json

# Read a conversation with full message history
skill front conversation <conversation-id> --messages --json

# Read a single message
skill front message <message-id> --json

Pattern: Start broad (inbox) → drill into specific conversations → read messages → take action.

Health & Diagnostics

# Deep system check (auth, env, DB, APIs)
skill doctor --json

# Test a specific app's webhook endpoint
skill health total-typescript --json

# List all registered apps
skill health --list --json

# DB connectivity
skill db-status --json

Auth

skill auth setup                  # One-command bootstrap
skill auth status --json          # Current provider + secret availability
skill auth oauth-spike --json     # Broker readiness check

Evals

# Run routing classifier eval
skill eval routing dataset.json --json

# With custom thresholds
skill eval routing dataset.json --min-precision 0.95 --min-recall 0.97 --json

# Local eval (no API needed)
skill eval-local routing dataset.json --json

# Pipeline eval
skill eval-pipeline run --json

Inngest / Pipeline Debugging

# Recent events
skill inngest events --after 1h --json

# Inspect a specific event
skill inngest event <event-id> --json

# Run details (step trace)
skill inngest run <run-id> --json

# Recent failures
skill inngest failures --after 2h --json

App Integration

# Initialize new app
skill init my-app --json

# Tools for a specific app
skill tools list --json
skill tools search <app> <query> --json
skill tools lookup <app> <email> --json
skill tools purchases <app> <user-id> --json

Responses & Datasets

skill responses list --json
skill responses get <response-id> --context --json
skill dataset build --output /tmp/dataset.json --json

Config & Keys

# View config
skill config show --json

# Add personal key override
skill keys add FRONT_API_TOKEN=<token>
skill keys status --json

Axiom (Logs)

skill axiom query "status >= 500" --json
skill axiom tail --json

Linear

skill linear issues --json
skill linear issue <id> --json

Memory

skill memory search <query> --json
skill memory add <text> --json

Deploy Info

skill deploys list --json
skill deploys status --json

MCP Server

# Start MCP server for AI editor integration (Claude Code, Cursor, etc.)
# Exposes 9 Front tools over JSON-RPC stdio
skill mcp

Agent Usage Patterns

JSON Everything

Always use --json or --format json. The CLI returns structured envelopes:

{
  "success": true,
  "data": { ... },
  "meta": { "count": 20, "hasMore": true }
}

Errors:

{
  "success": false,
  "error": "Missing Bearer token",
  "fix": "Run: skill auth setup"
}

Exit Codes

0 = success
1 = error (check JSON error field)

Suppress Hints

The CLI shows adaptive onboarding hints to new users on stderr. Suppress with:

--json (auto-suppresses)
--quiet
Piped output (non-TTY auto-suppresses)

Idempotent Operations

Safe to retry: doctor, health, auth status, front inbox, all read ops. Write ops (init, keys add, front reply) are NOT idempotent.

Architecture

skillrecordings/support/
├── apps/
│   ├── front/      # Front webhook handler + OAuth broker (Vercel)
│   ├── slack/      # Slack integration (Vercel)
│   └── web/        # Support dashboard (Vercel)
├── packages/
│   ├── cli/        # This CLI (@skillrecordings/cli)
│   ├── core/       # Shared routing, classification, response generation
│   ├── database/   # Prisma schema + client
│   ├── sdk/        # Integration SDK for app properties
│   ├── front-sdk/  # Front API client
│   ├── memory/     # Vector search for support context
│   └── review-tui/ # TUI for reviewing agent responses
├── skills/         # Agent skills (auto-linked to ~/.agents, ~/.pi, ~/.claude)
└── k8s/            # Kubernetes manifests (if applicable)

OAuth Broker (v0.19.0+)

The broker runs on Vercel at skill-support-agent-front.vercel.app:

Endpoint	Purpose
`POST /api/auth/device/start`	Start GitHub device flow
`POST /api/auth/device/poll`	Exchange device code for session
`POST /api/auth/session/refresh`	Refresh, re-check org membership
`POST /api/env/materialize`	Age-encrypted env delivery

Flow: CLI device flow → GitHub approve → broker checks skillrecordings org → session tokens (15min/8hr) → env materialized server-side via 1Password → re-encrypted to ephemeral client key → decrypted in memory only.

Updating This Skill

This skill is installed automatically when you run skill from within the support repo. The CLI's autoLinkSkills symlinks skills/ into:

~/.agents/skills/skill-support/
~/.pi/agent/skills/skill-support/
~/.claude/skills/skill-support/

To force a refresh after updating the repo:

cd /path/to/skillrecordings/support
git pull
skill doctor  # triggers autoLinkSkills

The binary install also updates the skill via the install script.

Key Locations

Item	Path
Binary	`~/.local/bin/skill`
Config dir	`~/.config/skill/`
Age key (legacy)	`~/.config/skill/age.key`
Session cache	`~/.config/skill/session.json`
Usage tracking	`~/.config/skill/usage.json`
Secret refs	`packages/cli/src/core/secret-refs.ts`
Encrypted env	`packages/cli/.env.encrypted`
Skills source	`skills/` (repo root, auto-linked)

Do / Don't

Do:

Start with skill doctor --json when anything is broken
Use --json on every command for agent workflows
Use IDs from prior output in follow-up commands
Start broad (inbox, events) then drill down
Run skill auth setup when sessions expire

Don't:

Don't parse stdout without --json (hints go to stderr but format varies)
Don't assume inbox/app IDs — fetch and verify first
Don't run destructive ops without explicit user request
Don't hardcode paths — use skill config show --json to discover
Don't skip skill doctor when debugging — it catches 90% of issues