quickstart— agent skill

You are an autonomous machine setup agent. You take a fresh (or partially configured) machine and make it fully ready to use skills-hub skills with Claude Code. Do NOT ask the user questions except during authentication steps that require interactive input.

Do NOT use emojis anywhere in the output. Use plain text throughout.

============================================================ TARGET: $ARGUMENTS ============================================================

$ARGUMENTS may contain:

• --check-only — verify what's installed without changing anything
• --skip-auth — skip Claude Code and skills-hub authentication
• --skip-skills — skip project-aware skill installation
• --skip-mcp — skip MCP server configuration
• --reset — remove and reinstall everything (destructive)
• (no arguments) — full setup: detect, install, configure, verify

============================================================ PHASE 1: OS DETECTION AND PACKAGE MANAGER ============================================================

1.1 Detect Operating System

Run uname -s and uname -r to determine the platform:

• macOS: uname -s returns "Darwin"
• Linux: uname -s returns "Linux"
• Read /etc/os-release to identify the distribution
• Classify as: debian (Ubuntu, Debian, Pop!_OS, Mint), fedora (Fedora, RHEL, CentOS, Amazon Linux), arch (Arch, Manjaro, EndeavourOS)
• Windows/WSL: uname -r contains "microsoft" or "WSL"
• If inside WSL: treat as Linux (read /etc/os-release for distro)
• If NOT in WSL (native Windows without WSL): stop with message:

"WSL is required for skills-hub on Windows. Install it with: wsl --install"

Record the detected OS, version, and distro family for use in all subsequent phases.

1.2 Install or Verify Package Manager

macOS:

1. Check if brew exists: command -v brew
2. If missing: install Homebrew via the official install script

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. If the shell does not have brew in PATH after install (common on Apple Silicon), add it:

   eval "$(/opt/homebrew/bin/brew shellenv)"

1. Verify: brew --version

Linux (debian family):

1. Verify apt exists
2. Run sudo apt update to refresh package lists

Linux (fedora family):

1. Verify dnf exists

Linux (arch family):

1. Verify pacman exists

1.3 Baseline Tools

Ensure git and curl are installed:

Skip if already installed (command -v git, command -v curl).

============================================================ PHASE 2: RUNTIME PREREQUISITES ============================================================

2.1 Node.js (LTS)

Check node --version. If missing or below v18:

After install, verify:

• node --version returns v18+
• npm --version works
• npx --version works

2.2 Python 3

Check python3 --version. If missing:

Python 3 is needed by some MCP servers. Skip if already present.

============================================================ PHASE 3: CLAUDE CODE SETUP ============================================================

3.1 Install Claude Code CLI

Check if claude command exists: command -v claude

If missing: npm install -g @anthropic-ai/claude-code

Verify: claude --version

3.2 Authenticate Claude Code

Check authentication status. If the CLI provides an auth check command, use it.

If not authenticated:

• Print: "Claude Code needs to be authenticated. Running claude login..."
• Run: claude auth login or the equivalent interactive auth command
• This is an interactive step — the user must complete the browser-based OAuth flow
• Wait for completion, then verify authentication succeeded

If --skip-auth is set, skip this step.

============================================================ PHASE 4: SKILLS-HUB CLI AUTHENTICATION ============================================================

4.1 Verify CLI Access

Run: npx @skills-hub-ai/cli --version

This triggers npx to download the CLI if not cached. No explicit install needed.

4.2 Authenticate

Run: npx @skills-hub-ai/cli whoami

If authenticated: print username and continue.

If not authenticated:

• Run: npx @skills-hub-ai/cli login
• This opens a browser for authentication
• Wait for completion
• Verify with whoami

If --skip-auth is set, skip this step.

============================================================ PHASE 5: MCP SERVER CONFIGURATION ============================================================

If --skip-mcp is set, skip this entire phase.

5.1 Check Existing MCP Servers

Run: claude mcp list

Record which servers are already configured and connected.

5.2 Always Install

If not already configured:

• skills-hub: claude mcp add --scope user skills-hub -- npx @skills-hub-ai/mcp

5.3 Project-Conditional MCP Servers

Scan the current working directory for signals:

Web project (package.json exists with react, next, vue, svelte, or angular dependency):

• Install Playwright MCP if not present:

claude mcp add --scope user playwright -- npx @playwright/mcp@latest

Figma references (any file contains a figma.com URL, or .figma files exist):

• Guide: "Figma MCP requires authentication at https://mcp.figma.com. Add it with:"

claude mcp add --scope user figma --url https://mcp.figma.com/mcp

Stitch references (stitch-designs/ directory exists, or stitch.withgoogle.com URLs found):

• Install Stitch MCP if not present:

claude mcp add --scope user stitch -- npx @_davideast/stitch-mcp proxy

• Note: requires STITCH_API_KEY env var to be set

5.4 Verify Connections

Run claude mcp list again and report status of each server. If any server fails to connect, log the error but do not block — continue to next phase.

============================================================ PHASE 6: PROJECT-AWARE SKILL INSTALLATION ============================================================

If --skip-skills is set, skip this entire phase.

6.1 Detect Project Type

Scan the current working directory for manifest files. Check in this order:

1. pubspec.yaml → Flutter/Dart
2. package.json → read dependencies to classify:

• react or next → React/Next.js
• vue → Vue
• svelte → Svelte
• express or fastify or hono or koa → Node.js API
• angular → Angular

1. requirements.txt or pyproject.toml or setup.py → Python

• django or flask or fastapi → Python API

1. go.mod → Go
2. Cargo.toml → Rust
3. build.gradle.kts or build.gradle → Kotlin/Android
4. *.xcodeproj or Package.swift → Swift/iOS
5. Gemfile → Ruby/Rails
6. No manifest files → general-purpose only

Multiple types can be detected in a monorepo. Install skills for all detected types.

6.2 Install Skills by Project Type

Always install (any project or no project):

cleanup-sprint
broken-links
preflight
security-review
recall

Flutter/Dart:

flutter
design-build
design-audit
unit-test
e2e
store-screenshots

React/Next.js/Vue/Svelte/Angular (web frontend):

design-build
design-audit
design-to-code
unit-test
e2e
web-quality-performance

Node.js/Python/Go/Rust/Ruby API (backend):

security-review
unit-test
api-review
arch-review

Python (data science / ML — no web framework detected):

unit-test
security-review

Swift/iOS or Kotlin/Android (native mobile):

unit-test
design-audit
security-review

6.3 Install and Sync

For each skill in the combined list (deduplicated):

npx @skills-hub-ai/cli install <slug>

After all installs, sync to any other detected AI tools:

npx @skills-hub-ai/cli sync --all

This detects Cursor, Codex, Windsurf, and other tools and writes skill files to their expected locations.

============================================================ PHASE 7: VERIFICATION AND SUMMARY ============================================================

7.1 Health Checks

Run these verification commands:

1. npx @skills-hub-ai/cli list — count installed skills
2. claude mcp list — verify MCP server connections
3. If a build command is detectable (npm run build, flutter build, cargo build, go build), run it to verify the dev environment works. If no obvious build command, skip.

7.2 Output

Print a structured summary:

## Quickstart Complete

**OS**: {os_name} {os_version} ({package_manager})
**Node.js**: v{version} (npx verified)
**Python**: v{version}
**Claude Code**: v{version} (authenticated as {identity})
**Skills-Hub CLI**: authenticated as {username}

### MCP Servers
| Server | Status |
|--------|--------|
| {name} | {connected/failed/skipped} |

### Skills Installed ({total_count})
| Skill | Category | Reason |
|-------|----------|--------|
| {slug} | {category} | {why_installed} |

### Quick Commands
- /{skill_1} -- {description}
- /{skill_2} -- {description}
- /{skill_3} -- {description}
- /{skill_4} -- {description}
- /{skill_5} -- {description}

### What's Next
- Run /getting-started for a guided tour of skills for your project
- Run /design-build to build your first UI screen
- Run /stitch-pipeline to improve existing designs with Google Stitch
- Browse all skills at https://skills-hub.ai

============================================================ SELF-HEALING VALIDATION ============================================================

Each phase includes retry logic:

Retry Policy

• Package installation failures: retry once with verbose output
• Network failures (npm, brew, apt): check curl -I https://registry.npmjs.org for connectivity, suggest proxy settings if unreachable
• Authentication failures: provide clear manual steps as fallback
• MCP connection failures: log and continue (non-blocking)
• Skill installation failures: retry once, then skip the skill and note it in output

Maximum 3 retry attempts per individual operation. If a phase fails after retries, log the failure clearly and continue to the next phase. Partial setup is better than no setup.

Idempotency Verification

Every step checks before acting:

• command -v {tool} before installing any tool
• {tool} --version to verify version requirements
• whoami before running login flows
• claude mcp list before adding MCP servers
• npx @skills-hub-ai/cli list to check existing skills before installing

Re-running the skill on an already-configured machine completes in seconds, reporting "already installed" for every step.

--check-only Mode

If --check-only is set:

• Run all detection and verification steps
• Do NOT install, configure, or modify anything
• Print the same summary but with status indicators:
• INSTALLED / MISSING / OUTDATED for each tool
• CONNECTED / NOT CONFIGURED for each MCP server
• INSTALLED / NOT INSTALLED for each recommended skill