From e0f4c0ffdab518e94e7439568a1a3acc73946347 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 11:21:51 +0000 Subject: [PATCH] feat(skill): add core CLI skill for Claude Code Adds a Claude Code skill that documents the core CLI commands and guides Claude to use the correct command for different tasks. Features: - Command quick reference table - Decision tree for common workflows - Common mistakes to avoid - Installation script for global install Install globally: curl -fsSL https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/install.sh | bash Or use from project .claude/skills/ directory. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/core/SKILL.md | 288 +++++++++++++++++++++++++++++++++ .claude/skills/core/install.sh | 40 +++++ 2 files changed, 328 insertions(+) create mode 100644 .claude/skills/core/SKILL.md create mode 100755 .claude/skills/core/install.sh diff --git a/.claude/skills/core/SKILL.md b/.claude/skills/core/SKILL.md new file mode 100644 index 0000000..ba598fb --- /dev/null +++ b/.claude/skills/core/SKILL.md @@ -0,0 +1,288 @@ +--- +name: core +description: Use when working in host-uk repositories, running tests, building, releasing, or managing multi-repo workflows. Provides the core CLI command reference. +--- + +# Core CLI + +The `core` command provides a unified interface for Go/Wails development, multi-repo management, and deployment. + +**Rule:** Always prefer `core ` over raw commands. It handles environment setup, output formatting, and cross-platform concerns. + +## Command Quick Reference + +| Task | Command | Notes | +|------|---------|-------| +| Run tests | `core test` | Sets macOS deployment target, filters warnings | +| Run tests with coverage | `core test --coverage` | Per-package breakdown | +| Run specific test | `core test --run TestName` | Regex filter | +| Build project | `core build` | Auto-detects project type | +| Build for targets | `core build --targets linux/amd64,darwin/arm64` | Cross-compile | +| Release | `core release` | Build + publish to GitHub/npm/Homebrew | +| Check environment | `core doctor` | Verify tools installed | +| Multi-repo status | `core health` | Quick summary across repos | +| Multi-repo workflow | `core work` | Status + commit + push | +| Commit dirty repos | `core commit` | Claude-assisted commit messages | +| Push repos | `core push` | Push repos with unpushed commits | +| Pull repos | `core pull` | Pull repos that are behind | +| List issues | `core issues` | Open issues across repos | +| List PRs | `core reviews` | PRs needing review | +| Check CI | `core ci` | GitHub Actions status | +| Generate SDK | `core sdk` | Generate API clients from OpenAPI | +| Sync docs | `core docs sync` | Sync docs across repos | + +## Testing + +**Always use `core test` instead of `go test`.** + +```bash +# Run all tests with coverage summary +core test + +# Detailed per-package coverage +core test --coverage + +# Test specific packages +core test --pkg ./pkg/crypt + +# Run specific tests +core test --run TestHash +core test --run "Test.*Good" + +# Skip integration tests +core test --short + +# Race detection +core test --race + +# JSON output for CI/parsing +core test --json +``` + +**Why:** Sets `MACOSX_DEPLOYMENT_TARGET=26.0` to suppress linker warnings, filters noise from output, provides colour-coded coverage. + +### JSON Output + +For programmatic use: + +```json +{ + "passed": 14, + "failed": 0, + "skipped": 0, + "coverage": 75.1, + "exit_code": 0, + "failed_packages": [] +} +``` + +## Building + +**Always use `core build` instead of `go build`.** + +```bash +# Auto-detect and build +core build + +# Build for specific targets +core build --targets linux/amd64,darwin/arm64 + +# Build Docker image +core build --type docker + +# Build LinuxKit image +core build --type linuxkit --format qcow2-bios + +# CI mode (JSON output) +core build --ci +``` + +**Why:** Handles cross-compilation, code signing, archiving, checksums, and CI output formatting. + +## Multi-Repo Workflow + +When working across host-uk repositories: + +```bash +# Quick health check +core health +# Output: "18 repos │ clean │ synced" + +# Full status table +core work --status + +# Commit + push workflow +core work + +# Commit dirty repos with Claude +core commit + +# Push repos with unpushed commits +core push + +# Pull repos that are behind +core pull +``` + +### Dependency Analysis + +```bash +# What depends on core-php? +core impact core-php +``` + +## GitHub Integration + +Requires `gh` CLI authenticated. + +```bash +# Open issues across all repos +core issues + +# Include closed issues +core issues --all + +# PRs needing review +core reviews + +# CI status +core ci +``` + +## SDK Generation + +Generate API clients from OpenAPI specs: + +```bash +# Generate all configured SDKs +core sdk + +# Generate specific language +core sdk --lang typescript +core sdk --lang php + +# Specify OpenAPI spec +core sdk --spec ./openapi.yaml +``` + +## Documentation + +```bash +# List docs across repos +core docs list + +# Sync docs to central location +core docs sync +``` + +## Environment Setup + +```bash +# Check development environment +core doctor + +# Clone all repos from registry +core setup + +# Search GitHub repos +core search + +# Clone a specific repo +core install +``` + +## PHP Development + +```bash +# Start PHP dev environment +core php dev + +# Run artisan commands +core php artisan + +# Run composer +core php composer +``` + +## Container Management + +```bash +# Run LinuxKit image +core run server.iso + +# List running containers +core ps + +# Stop container +core stop + +# View logs +core logs + +# Execute command in container +core exec +``` + +## Decision Tree + +``` +Need to run tests? + └── core test [--coverage] [--pkg ] + +Need to build? + └── core build [--targets ] + +Need to release? + └── core release + +Working across multiple repos? + └── Quick check: core health + └── Full workflow: core work + └── Just commit: core commit + └── Just push: core push + +Need GitHub info? + └── Issues: core issues + └── PRs: core reviews + └── CI: core ci + +Setting up environment? + └── Check: core doctor + └── Clone all: core setup +``` + +## Common Mistakes + +| Wrong | Right | Why | +|-------|-------|-----| +| `go test ./...` | `core test` | Missing deployment target, noisy output | +| `go build` | `core build` | Missing cross-compile, signing, checksums | +| `git status` in each repo | `core health` | Slow, manual | +| `gh pr list` per repo | `core reviews` | Aggregated view | +| Manual commits across repos | `core commit` | Consistent messages, Co-Authored-By | + +## Configuration + +Core reads from `.core/` directory: + +``` +.core/ +├── release.yaml # Release targets +├── build.yaml # Build settings +└── linuxkit/ # LinuxKit templates +``` + +And `repos.yaml` in workspace root for multi-repo management. + +## Installation + +```bash +# Go install +go install github.com/host-uk/core/cmd/core@latest + +# Or from source +cd /path/to/core +go install ./cmd/core/ +``` + +Verify: `core doctor` \ No newline at end of file diff --git a/.claude/skills/core/install.sh b/.claude/skills/core/install.sh new file mode 100755 index 0000000..560faa8 --- /dev/null +++ b/.claude/skills/core/install.sh @@ -0,0 +1,40 @@ +#!/bin/bash +# Install the core skill globally for Claude Code +# +# Usage: +# curl -fsSL https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/install.sh | bash +# +# Or if you have the repo cloned: +# ./.claude/skills/core/install.sh + +set -e + +SKILL_DIR="$HOME/.claude/skills/core" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Check if running from repo or downloading +if [ -f "$SCRIPT_DIR/SKILL.md" ]; then + SOURCE_DIR="$SCRIPT_DIR" +else + # Download from GitHub + TEMP_DIR=$(mktemp -d) + trap "rm -rf $TEMP_DIR" EXIT + + echo "Downloading core skill..." + curl -fsSL "https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/SKILL.md" -o "$TEMP_DIR/SKILL.md" + SOURCE_DIR="$TEMP_DIR" +fi + +# Create skills directory if needed +mkdir -p "$SKILL_DIR" + +# Copy skill file +cp "$SOURCE_DIR/SKILL.md" "$SKILL_DIR/SKILL.md" + +echo "Installed core skill to $SKILL_DIR" +echo "" +echo "Usage:" +echo " - Claude will auto-invoke when working in host-uk repos" +echo " - Or type /core to invoke manually" +echo "" +echo "Commands available: core test, core build, core release, core work, etc." \ No newline at end of file