@kennethsolomon/shipkit 3.15.1 → 3.16.0

package/skills/sk:ci/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: sk:ci
+description: "Set up Claude Code GitHub Actions or GitLab CI integration. Generates workflow files for PR review, issue triage, nightly audits, and release automation. Supports direct API, AWS Bedrock, and Google Vertex AI."
+disable-model-invocation: true
+argument-hint: "[github|gitlab] [--bedrock|--vertex]"
+---
+
+# /sk:ci
+
+Set up Claude Code CI/CD integration: GitHub Actions or GitLab CI.
+
+## Before You Start
+
+1. Read `CLAUDE.md` to understand the project stack and repository type
+2. Check if `.github/workflows/` or `.gitlab-ci.yml` already exists
+3. Detect provider: `git remote -v` — github.com → GitHub Actions, gitlab.com → GitLab CI
+
+## Step 1 — Choose Provider
+
+**GitHub Actions** (default):
+- Quick setup: Run `/install-github-app` in Claude Code terminal
+- Manual setup: follow the instructions below
+
+**GitLab CI**: generate `.gitlab-ci.yml` with inline Claude Code runner
+
+If user doesn't specify, ask: "GitHub Actions or GitLab CI?"
+
+## Step 2 — Choose Authentication
+
+For GitHub Actions, ask:
+
+> "Which API provider? (1) Anthropic direct API — simplest, (2) AWS Bedrock — enterprise/data residency, (3) Google Vertex AI — enterprise/GCP"
+
+For option 1 (direct API), proceed to Step 3.
+For options 2 or 3, follow the Enterprise Setup section below.
+
+## Step 3 — Choose Workflows
+
+Present a checklist. Ask the user which they want:
+
+```
+Which workflows do you want to set up? (select all that apply)
+
+[1] @claude trigger — respond to @claude mentions in PR/issue comments
+[2] Auto PR review — review every PR automatically on open/sync
+[3] Issue triage — auto-label and respond to new issues
+[4] Nightly audit — daily code quality / security / SEO review
+[5] Release automation — auto-generate changelog on tag push
+```
+
+Generate only the selected workflows.
+
+## GitHub Actions — Workflow Templates
+
+### [1] @claude Trigger (responds to @claude mentions)
+
+Create `.github/workflows/claude.yml`:
+
+```yaml
+name: Claude Code
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+### [2] Auto PR Review
+
+Create `.github/workflows/claude-review.yml`:
+
+```yaml
+name: Claude PR Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Review this pull request for:
+            1. Correctness — logic errors, edge cases, off-by-one errors
+            2. Security — OWASP Top 10, injection, auth issues
+            3. Performance — N+1 queries, unnecessary allocations
+            4. Test coverage — missing tests for new code paths
+
+            Post findings as inline review comments on the diff.
+            If the PR is clean, post a single approval comment.
+          claude_args: "--max-turns 5"
+```
+
+### [3] Issue Triage
+
+Create `.github/workflows/claude-triage.yml`:
+
+```yaml
+name: Claude Issue Triage
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Triage this new issue:
+            1. Add appropriate labels (bug, enhancement, question, documentation)
+            2. Ask for missing information (reproduction steps, OS, version)
+            3. Check if a similar issue already exists — if so, link it
+            4. Estimate complexity: trivial / small / medium / large
+
+            Post a single helpful comment. Be concise.
+          claude_args: "--max-turns 3"
+```
+
+### [4] Nightly Audit
+
+Create `.github/workflows/claude-nightly.yml`:
+
+```yaml
+name: Claude Nightly Audit
+on:
+  schedule:
+    - cron: "0 2 * * *"   # 2 AM UTC daily
+  workflow_dispatch:        # allow manual trigger
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Run a nightly audit of this repository:
+            1. Security: Check for new vulnerabilities, outdated dependencies
+            2. Code quality: Identify patterns that should be refactored
+            3. Documentation gaps: Find public APIs or components with no docs
+            4. Dead code: Identify unused exports, orphaned files
+
+            If critical findings exist, create a GitHub issue titled
+            "Nightly Audit [date] — N critical findings" with a full report.
+            If clean, no action needed.
+          claude_args: "--max-turns 10 --model claude-sonnet-4-6"
+```
+
+### [5] Release Automation
+
+Create `.github/workflows/claude-release.yml`:
+
+```yaml
+name: Claude Release Notes
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Generate release notes for this tag based on commits since the last tag.
+            Group by: Features, Bug Fixes, Performance, Breaking Changes.
+            Keep it concise — 3-5 bullet points per section maximum.
+            Create a GitHub Release with these notes.
+          claude_args: "--max-turns 5"
+```
+
+## Enterprise Setup — AWS Bedrock
+
+For Bedrock, update each workflow's `steps` to add:
+
+```yaml
+# After actions/checkout, before claude-code-action:
+- name: Configure AWS Credentials
+  uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
+    aws-region: us-west-2
+
+# In claude-code-action:
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_bedrock: "true"
+    claude_args: "--model us.anthropic.claude-sonnet-4-6 --max-turns 10"
+    # No anthropic_api_key needed — uses AWS credentials
+```
+
+**Required secrets:** `AWS_ROLE_TO_ASSUME`
+
+**Required AWS setup:**
+1. Configure GitHub OIDC identity provider in AWS IAM
+2. Create IAM role with `AmazonBedrockFullAccess` that trusts GitHub Actions
+3. Enable Claude model access in AWS Bedrock console
+
+## Enterprise Setup — Google Vertex AI
+
+```yaml
+# After actions/checkout, before claude-code-action:
+- name: Authenticate to Google Cloud
+  id: auth
+  uses: google-github-actions/auth@v2
+  with:
+    workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+    service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_vertex: "true"
+    claude_args: "--model claude-sonnet-4@20250514 --max-turns 10"
+  env:
+    ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
+    CLOUD_ML_REGION: us-east5
+```
+
+**Required secrets:** `GCP_WORKLOAD_IDENTITY_PROVIDER`, `GCP_SERVICE_ACCOUNT`
+
+## Custom GitHub App (Optional)
+
+For branded bot usernames or enterprise requirements:
+
+1. Create GitHub App at https://github.com/settings/apps/new
+   - Permissions: Contents (R+W), Issues (R+W), Pull Requests (R+W)
+2. Generate a private key and save it
+3. Add secrets: `APP_ID`, `APP_PRIVATE_KEY`
+4. Add to workflow before `claude-code-action`:
+
+```yaml
+- name: Generate GitHub App token
+  id: app-token
+  uses: actions/create-github-app-token@v2
+  with:
+    app-id: ${{ secrets.APP_ID }}
+    private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+- uses: anthropics/claude-code-action@v1
+  with:
+    github_token: ${{ steps.app-token.outputs.token }}
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## GitLab CI
+
+Create `.gitlab-ci.yml` (or append to existing):
+
+```yaml
+claude-review:
+  stage: review
+  image: node:20-alpine
+  only:
+    - merge_requests
+  script:
+    - npm install -g @anthropic-ai/claude-code
+    - git diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD > /tmp/diff.patch
+    - claude --print --max-turns 5 \
+        "Review this diff for security, correctness, and test coverage: $(cat /tmp/diff.patch). Post findings as a structured report."
+  variables:
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+```
+
+**Required:** Add `ANTHROPIC_API_KEY` to GitLab CI/CD Variables (Settings → CI/CD → Variables).
+
+## After Setup
+
+1. Commit the generated workflow files
+2. Add `ANTHROPIC_API_KEY` to repository secrets (Settings → Secrets → Actions → New secret)
+3. For quick setup, run `/install-github-app` in Claude Code to install the GitHub App automatically
+4. Test by tagging `@claude` in a PR or issue comment
+
+## Customizing Claude's Behavior
+
+Claude reads `CLAUDE.md` in your repository root during CI runs. Add CI-specific rules there:
+
+```markdown
+## CI/CD Rules
+- In PR reviews: focus on correctness and security — skip style comments
+- In issue triage: always ask for reproduction steps for bug reports
+- Maximum PR review length: 10 bullet points total
+```

package/skills/sk:context/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: sk:context
 description: "Session initializer — loads all project context files and outputs a formatted session brief. Run this at the start of every conversation to orient the AI and yourself."
+model: haiku
 ---
 
 # /sk:context — Session Brief + Context Loader

package/skills/sk:e2e/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: sk:e2e
 description: "Run E2E behavioral verification as the final quality gate before finalize. Prefers Playwright CLI when playwright.config.ts is detected; falls back to agent-browser otherwise. Tests the complete, reviewed, secure implementation from a user's perspective."
+model: sonnet
 ---
 
 # /sk:e2e

package/skills/sk:fast-track/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sk:fast-track
 description: Abbreviated workflow for small, clear changes — skip planning ceremony, keep all quality gates
-allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent, Skill
 ---
 
 # Fast-Track Flow

package/skills/sk:gates/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sk:gates
 description: Run all quality gates in optimized parallel batches — one command instead of six
-allowed_tools: Agent, Read, Write, Bash, Glob, Grep
+allowed-tools: Agent, Read, Write, Bash, Glob, Grep
 ---
 
 # Gates Orchestrator

package/skills/sk:lint/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: sk:lint
 description: "Auto-detect and run all linting tools: formatters first (sequential), then analyzers in parallel. Fix and re-run until clean."
+model: haiku
 ---
 
 # /sk:lint

package/skills/sk:perf/SKILL.md

@@ -2,6 +2,7 @@
 name: sk:perf
 description: Performance audit. Use before /sk:review to catch performance issues: bundle size, N+1 queries, slow DB queries, Core Web Vitals, memory leaks, caching opportunities. Auto-detects stack. Fixes critical/high in-scope findings and auto-commits. Logs pre-existing issues to tech-debt.
 license: Complete terms in LICENSE.txt
+model: sonnet
 ---
 
 ## Purpose

package/skills/sk:plugin/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: sk:plugin
+description: "Package your project's custom skills, agents, hooks, and MCP servers as a distributable Claude Code plugin with a plugin.json manifest. Helps teams share Claude Code customizations."
+disable-model-invocation: true
+argument-hint: "[--name <plugin-name>] [--output <dir>]"
+---
+
+# /sk:plugin
+
+Package your custom Claude Code skills, agents, hooks, and MCP servers as a distributable plugin.
+
+> **Note for ShipKit users:** ShipKit itself is distributed via npm (`npx @kennethsolomon/shipkit`), not as a plugin — that gives you shorter `/sk:*` command names and global installation. This skill is for packaging YOUR OWN project-specific customizations to share with your team.
+
+## When to Use This
+
+Use `/sk:plugin` when you have:
+- Custom skills in `.claude/skills/` that your team wrote for your project
+- Custom agents in `.claude/agents/` you want to share
+- Hooks in `settings.json` you want to distribute
+- MCP server configs in `.mcp.json` you want to bundle
+
+**Don't use this** to re-package ShipKit itself — it's already on npm.
+
+## Step 1 — Discover What to Package
+
+Scan the project for custom Claude Code assets:
+
+```bash
+# Check for custom skills (not ShipKit skills)
+ls ~/.claude/skills/ 2>/dev/null
+ls .claude/skills/ 2>/dev/null
+
+# Check for custom agents
+ls .claude/agents/ 2>/dev/null
+
+# Check for hooks in settings.json
+cat .claude/settings.json 2>/dev/null | grep -A 20 '"hooks"'
+
+# Check for MCP config
+cat .mcp.json 2>/dev/null
+cat .claude/mcp.json 2>/dev/null
+```
+
+Report what was found. Ask the user:
+> "I found: [N skills], [N agents], [N hooks], [N MCP servers]. Which should be included in the plugin?"
+
+## Step 2 — Gather Plugin Info
+
+Ask:
+
+```
+Plugin name (kebab-case, e.g. "my-team-tools"):
+Plugin version (default: 1.0.0):
+Plugin description (1 sentence):
+Author (name or org):
+```
+
+## Step 3 — Create Plugin Structure
+
+Create the plugin directory structure:
+
+```
+<plugin-name>/
+├── plugin.json              # manifest
+├── skills/                  # selected skills
+│   └── <skill-name>/
+│       └── SKILL.md
+├── agents/                  # selected agents
+│   └── <agent-name>.md
+├── hooks/
+│   └── hooks.json           # selected hooks
+├── .mcp.json                # MCP server configs (if any)
+└── README.md                # auto-generated install instructions
+```
+
+### plugin.json manifest
+
+```json
+{
+  "name": "<plugin-name>",
+  "version": "1.0.0",
+  "description": "<description>",
+  "author": "<author>",
+  "skills": [
+    { "name": "<skill-name>", "path": "skills/<skill-name>/SKILL.md" }
+  ],
+  "agents": [
+    { "name": "<agent-name>", "path": "agents/<agent-name>.md" }
+  ],
+  "hooks": "hooks/hooks.json",
+  "mcp": ".mcp.json"
+}
+```
+
+### hooks/hooks.json format
+
+Convert from `settings.json` format:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "your-hook-command" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Step 4 — Copy Selected Assets
+
+For each selected skill:
+1. Copy the skill directory to `<plugin-name>/skills/<skill-name>/`
+2. Update any hardcoded paths to use `${CLAUDE_SKILL_DIR}` for portability
+
+For each selected agent:
+1. Copy the `.md` file to `<plugin-name>/agents/`
+2. Review for hardcoded project-specific paths
+
+For hooks:
+1. Extract selected hooks from `settings.json`
+2. Write to `<plugin-name>/hooks/hooks.json`
+
+For MCP:
+1. Copy relevant entries from `.mcp.json` to `<plugin-name>/.mcp.json`
+2. Replace hardcoded paths with `${CLAUDE_PLUGIN_DIR}` placeholders
+
+## Step 5 — Generate README.md
+
+Create `<plugin-name>/README.md`:
+
+```markdown
+# <plugin-name>
+
+<description>
+
+## Install
+
+### Option 1: Copy to project
+```bash
+cp -r <plugin-name>/.claude/skills/* .claude/skills/
+cp -r <plugin-name>/.claude/agents/* .claude/agents/
+```
+
+### Option 2: Plugin install (when supported)
+```bash
+# In Claude Code terminal:
+/plugin install ./<plugin-name>
+```
+
+### Option 3: npm (if published)
+```bash
+npx <plugin-name>
+```
+
+## Included
+
+### Skills
+<list skills with descriptions>
+
+### Agents
+<list agents with descriptions>
+
+### Hooks
+<list hooks with what they do>
+
+## Configuration
+
+<any required env vars or config>
+```
+
+## Step 6 — Validate
+
+Check the plugin is well-formed:
+
+```bash
+# All referenced files exist
+# plugin.json is valid JSON
+# Skills have valid frontmatter (name, description)
+# Agents have valid frontmatter (name, description, model, tools)
+# hooks.json follows the correct event/matcher format
+```
+
+Report: "Plugin `<name>` created at `./<plugin-name>/` — N skills, N agents, N hooks."
+
+## Step 7 — Distribution Options
+
+Present options:
+
+**Option A — Share within team (simplest):**
+```bash
+# Commit the plugin directory to your repo
+git add <plugin-name>/
+git commit -m "feat: add <plugin-name> Claude Code plugin"
+# Team members run the setup script or copy manually
+```
+
+**Option B — npm package:**
+```bash
+# Add to package.json:
+# "bin": { "<plugin-name>": "bin/install.js" }
+# The install.js copies files to ~/.claude/skills/ and ~/.claude/agents/
+npm publish
+# Install: npx <plugin-name>
+```
+
+**Option C — Future: Plugin marketplace**
+When Anthropic launches a plugin marketplace, you'll be able to submit via:
+`https://claude.ai/settings/plugins/submit`
+
+## Updating an Existing Plugin
+
+If a `plugin.json` already exists in the target directory:
+1. Show a diff of what changed since last packaging
+2. Ask which changes to include
+3. Bump the patch version automatically
+4. Update README.md

package/skills/sk:release/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: sk:release
 description: "Automate releases: bump version, update CHANGELOG, create git tag, push to GitHub. Supports --android and --ios flags to run a full App Store / Play Store readiness audit before release — checks configs, permissions, signing, icons, store listing requirements, and guides you step-by-step through fixes. Use this whenever someone wants to release, publish, deploy, or submit an app to the App Store, Play Store, Google Play, or Apple App Store."
+disable-model-invocation: true
+argument-hint: "[android|ios]"
 ---
 
 # Release Automation Skill

package/skills/sk:retro/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sk:retro
 description: Post-ship retrospective analyzing velocity, blockers, and patterns to generate actionable improvements
-allowed_tools: Read, Glob, Grep, Bash, Write
+allowed-tools: Read, Glob, Grep, Bash, Write
 ---
 
 # Retrospective

package/skills/sk:reverse-doc/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: sk:reverse-doc
 description: Generate architecture and design documentation from existing code by analyzing patterns and asking clarifying questions
-allowed_tools: Read, Glob, Grep, Write, Agent
+allowed-tools: Read, Glob, Grep, Write, Agent
+context: fork
+agent: general-purpose
 ---
 
 # Reverse Document

package/skills/sk:review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: sk:review
 description: "Rigorous self-review of all branch changes across 7 dimensions: correctness, security, performance, reliability, design quality, best practices, and testing. Report-only — no PR creation (that's /sk:finish-feature's job). Use when code is complete and ready for review before merging."
+model: sonnet
 ---
 
 # Self-Review

package/skills/sk:scope-check/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sk:scope-check
 description: Compare current implementation against the plan to detect scope creep
-allowed_tools: Read, Glob, Grep, Bash
+allowed-tools: Read, Glob, Grep, Bash
 ---
 
 # Scope Check