@rfxlamia/skillkit 1.0.0

package/skills/verify-before-ship/references/verification-gates.md

@@ -0,0 +1,305 @@
+# Verification Gates — Full Specifications
+
+Complete reference for each of the 7 production safety gates.
+Each gate specifies: what to check, how to collect evidence, and what constitutes a pass.
+
+## Table of Contents
+
+- [G1: Tests Pass](#g1-tests-pass)
+- [G2: Security Scan Clean](#g2-security-scan-clean)
+- [G3: No Breaking Changes](#g3-no-breaking-changes)
+- [G4: Environment Config Validated](#g4-environment-config-validated)
+- [G5: Staging Deployment Verified](#g5-staging-deployment-verified)
+- [G6: Rollback Plan Documented](#g6-rollback-plan-documented)
+- [G7: Code Review Approved](#g7-code-review-approved)
+
+---
+
+## G1: Tests Pass
+
+**What to check:**
+- All unit tests pass
+- All integration tests pass
+- Any e2e tests covering the changed functionality pass
+- No test is skipped or marked xfail without a pre-existing, documented reason
+
+**How to collect evidence:**
+```bash
+# CI output (preferred)
+# Navigate to CI run → copy the final test summary
+
+# Local run
+npm test          # Node/JS
+pytest -v         # Python
+go test ./...     # Go
+./gradlew test    # Java/Kotlin
+bundle exec rspec # Ruby
+```
+
+**Pass criteria:**
+- All tests show PASS/GREEN
+- Zero unexpected failures
+- Zero unexplained skips
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- Any test failing
+- CI run not triggered (no output = no evidence)
+- "Tests will pass, I'm sure" without running them
+
+**Evidence template:**
+```
+GATE G1 Tests: CLEARED
+Evidence:
+  [paste CI summary or local output here]
+  Example: ✓ 247 passed, 0 failed — CI run #4521
+```
+
+---
+
+## G2: Security Scan Clean
+
+**What to check:**
+- No critical or high severity CVEs in dependencies
+- No hardcoded secrets, tokens, or credentials in diff
+- No new SQL injection / XSS / command injection patterns
+
+**How to collect evidence:**
+```bash
+# Dependency vulnerability scan
+npm audit --audit-level=high        # Node
+safety check                        # Python
+snyk test                           # Any (Snyk CLI)
+trivy fs .                          # Any (Trivy)
+
+# Secret detection
+git diff HEAD~1 | grep -i "password\|secret\|token\|api_key"
+trufflehog git --since-commit HEAD~1 .
+```
+
+**Pass criteria:**
+- Zero critical/high CVEs
+- No secrets detected in diff
+- Medium CVEs reviewed and accepted or mitigated
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- Any critical or high CVE present
+- Unreviewed secrets detected in diff
+- Scan was not run ("it's fine, no dependencies changed")
+
+**Evidence template:**
+```
+GATE G2 Security: CLEARED
+Evidence:
+  Dependency scan: 0 critical, 0 high (2 low — accepted)
+  Secret scan: clean
+  Tool: npm audit — 2026-03-13
+```
+
+---
+
+## G3: No Breaking Changes
+
+**What to check:**
+- API contracts not broken (no removed endpoints, no changed required fields)
+- Database schema migrations are backwards compatible or coordinated
+- No removed/renamed env vars that consumers depend on
+- Public interfaces (exported functions, types) not broken
+
+**How to collect evidence:**
+```bash
+# API diff
+git diff HEAD~1 -- "**/*.openapi.*" "**/*swagger*" "**/*schema*"
+
+# Database migration review
+cat migrations/latest.sql  # Confirm no DROP TABLE, no NOT NULL without default
+
+# Contract tests (if present)
+npm run test:contract
+pact verify
+```
+
+**Pass criteria:**
+- No uncoordinated breaking changes
+- Any breaking changes have a migration plan and all consumers updated
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- Removed API endpoints with active consumers
+- Additing NOT NULL column without default to existing table
+- Removed env var that dependent services use
+
+**Evidence template:**
+```
+GATE G3 Breaking Changes: CLEARED
+Evidence:
+  API diff: no breaking changes in openapi.yaml
+  DB migration: adds nullable column only
+  Contract tests: 12/12 passing
+```
+
+---
+
+## G4: Environment Config Validated
+
+**What to check:**
+- All required env vars for production are set
+- Config diff between staging and production is intentional
+- Feature flags, secrets, and infrastructure config reviewed
+- No staging-only config leaking to production
+
+**How to collect evidence:**
+```bash
+# Compare env files (sanitize secrets before pasting)
+diff .env.staging .env.production | grep "^[<>]" | sed 's/=.*/=***/'
+
+# Kubernetes/Docker: review configmap/secret diff
+kubectl diff -f k8s/production/
+
+# Terraform: plan output
+terraform plan -var-file=production.tfvars
+```
+
+**Pass criteria:**
+- All required vars confirmed present in production config
+- Any diff between staging and production is expected and documented
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- New env var added in code but not set in production
+- Unknown config difference between staging and production
+- "It's the same config as staging" without checking
+
+**Evidence template:**
+```
+GATE G4 Config: CLEARED
+Evidence:
+  New vars added: FEATURE_X_ENABLED (set to true in prod config ✓)
+  Config diff: 1 intentional difference — DEBUG=false in prod, true in staging
+```
+
+---
+
+## G5: Staging Deployment Verified
+
+**What to check:**
+- Code was deployed to staging before production
+- Smoke tests pass on staging (critical user paths work)
+- No error spike in staging logs after deploy
+
+**How to collect evidence:**
+```bash
+# Staging deploy confirmation
+curl -s https://staging.yourapp.com/health | jq .
+
+# Check staging logs for errors
+kubectl logs -n staging deployment/api --since=10m | grep -i error | tail -20
+
+# Smoke test
+curl -s https://staging.yourapp.com/api/v1/ping
+```
+
+**Pass criteria:**
+- Staging health endpoint returns 200
+- Critical user path (login, checkout, etc.) works manually
+- No new error pattern in logs
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- Code never deployed to staging ("we'll test in prod")
+- Staging shows errors that haven't been investigated
+- "Staging and prod are different so staging tests don't count"
+
+**Evidence template:**
+```
+GATE G5 Staging: CLEARED
+Evidence:
+  Staging deploy: 2026-03-13 14:32 UTC — build #891
+  Health: {"status":"ok","version":"1.4.2"}
+  Smoke test: login ✓, checkout ✓, API /ping ✓
+  Logs: 0 new errors in last 10 min
+```
+
+---
+
+## G6: Rollback Plan Documented
+
+**What to check:**
+- Rollback steps are written down and specific
+- Rollback has been validated (at minimum, reviewed for feasibility)
+- Who executes the rollback and how to trigger it is clear
+
+**Rollback plan minimum requirements:**
+1. Command or action to revert (specific, not "undo the change")
+2. Expected time to complete rollback
+3. How to verify rollback succeeded
+4. Who to notify
+
+**How to collect evidence:**
+```bash
+# Git rollback
+git revert HEAD --no-edit && git push origin main
+
+# Kubernetes rollback
+kubectl rollout undo deployment/api -n production
+kubectl rollout status deployment/api -n production
+
+# Feature flag toggle
+curl -X POST https://flags.yourapp.com/api/FEATURE_X/disable
+```
+
+**Pass criteria:**
+- Specific commands documented, not "revert the commit"
+- Steps are executable by someone other than the author
+- Database rollback steps included if schema changed
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- No rollback plan written ("we'll figure it out if needed")
+- Rollback plan is "we can just redeploy the old version" without specific commands
+- DB migration with no rollback migration
+
+**Evidence template:**
+```
+GATE G6 Rollback: CLEARED
+Evidence:
+  Rollback steps:
+  1. kubectl rollout undo deployment/api -n production
+  2. Verify: curl https://api.yourapp.com/health → {"version":"1.4.1"}
+  3. Notify: #incidents Slack channel
+  Estimated rollback time: ~3 minutes
+```
+
+---
+
+## G7: Code Review Approved
+
+**What to check:**
+- At least one reviewer (not the author) approved the PR
+- Review was substantive (not rubber-stamp)
+- Security-sensitive code had appropriate reviewer
+
+**How to collect evidence:**
+```bash
+# GitHub
+gh pr view <PR_NUMBER> --json reviews,reviewDecision
+
+# GitLab
+glab mr view <MR_IID>
+```
+
+**Pass criteria:**
+- Minimum 1 approval from non-author
+- Approval is on the current commit (no force-push after approval)
+- PR has no blocking comments unresolved
+
+**Fail criteria (DO NOT SHIP if any are true):**
+- No PR created ("it's a small fix")
+- PR approved by the author themselves
+- Unresolved blocking comments
+- Approved on an older commit, force-pushed after
+
+**Evidence template:**
+```
+GATE G7 Code Review: CLEARED
+Evidence:
+  PR: github.com/org/repo/pull/847
+  Approvals: @alice (2026-03-13 13:15 UTC)
+  Blocking comments: 0
+  Commit approved: a3f9d21 (current HEAD ✓)
+```

package/skills-manifest.json

@@ -0,0 +1,217 @@
+{
+  "skills": [
+    {
+      "name": "adversarial-review",
+      "description": "Adversarial review protocol for brainstorming, product planning, and technical architecture.",
+      "category": "quality",
+      "type": "skill",
+      "path": "skills/adversarial-review"
+    },
+    {
+      "name": "baby-education",
+      "description": "Makes agent explain concepts with extreme clarity for beginners learning new topics or projects. Uses analogies-first approach, visual mental models, and ELI5 style to transform complex technical explanations into accessible learning experiences. Trigger when user is new to a technology, starting a project, or explicitly requests simple explanations.",
+      "category": "engineering",
+      "type": "skill",
+      "path": "skills/baby-education"
+    },
+    {
+      "name": "been-there-done-that",
+      "description": "Guides an agent to document developer progress objectively after completing",
+      "category": "productivity",
+      "type": "skill",
+      "path": "skills/been-there-done-that"
+    },
+    {
+      "name": "coolhunter",
+      "description": "Trend intelligence and cultural signal detection for emerging news and behaviors.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/coolhunter"
+    },
+    {
+      "name": "creative-copywriting",
+      "description": "Master persuasive writing for social media with proven hooks, storytelling frameworks, and",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/creative-copywriting"
+    },
+    {
+      "name": "diverse-content-gen",
+      "description": "Agent workflow for generating highly diverse creative content using Verbalized Sampling (VS) technique. Use when user requests multiple variations, brainstorming, creative ideas, or when standard prompting produces repetitive outputs. Increases diversity by 1.6-2.1× while maintaining quality. Works for: blog posts, social media captions, stories, campaign ideas, product descriptions, taglines, and open-ended creative tasks.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/diverse-content-gen"
+    },
+    {
+      "name": "framework-critical-thinking",
+      "description": "Architectural framework for building AI agents with critical thinking capabilities - structured reasoning selection (CoT/ToT/GoT), metacognitive monitoring, self-verification, and cognitive bias detection. Use when building or enhancing AI agents that require reliable, self-correcting, and transparent reasoning.",
+      "category": "agent",
+      "type": "skill",
+      "path": "skills/framework-critical-thinking"
+    },
+    {
+      "name": "framework-initiative",
+      "description": "Framework for agents to understand implicit user intent, think before acting, and consider action impact. Uses STAR framework (Stop-Think-Analyze-Respond) to prevent literal execution that doesn't match context. Use when agent receives ambiguous requests, abstract commands like \"fix\", \"improve\", \"delete all\", or actions with potential wide-scope impact. Trigger on code modification requests without explicit scope constraints.",
+      "category": "agent",
+      "type": "skill",
+      "path": "skills/framework-initiative"
+    },
+    {
+      "name": "humanize-docs",
+      "description": "Transform AI-to-AI documentation into human-readable prose with personality.",
+      "category": "documentation",
+      "type": "skill",
+      "path": "skills/humanize-docs"
+    },
+    {
+      "name": "imagine",
+      "description": "Prepare detailed, professional prompts for Google Imagen 3/4 image generation. Supports character, environment, and object prompts using natural language with technical photography specifications. Extensible support for multiple art styles via reference files.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/imagine"
+    },
+    {
+      "name": "pre-deploy-checklist",
+      "description": "Intelligent pre-deployment QA checklist generator. Explores the codebase,",
+      "category": "deployment",
+      "type": "skill",
+      "path": "skills/pre-deploy-checklist"
+    },
+    {
+      "name": "prompt-engineering",
+      "description": "Use when you need to design effective LLM prompts. Intelligently selects optimal prompting methods (Chain of Thought, Few-Shot, Zero-Shot, ReAct, Tree of Thoughts, Self-Consistency) and output formats (XML, JSON, YAML, Natural Language) based on task complexity, target LLM, accuracy requirements, and available context. Trigger on prompt design, prompt optimization, or when choosing between prompting techniques.",
+      "category": "engineering",
+      "type": "skill",
+      "path": "skills/prompt-engineering"
+    },
+    {
+      "name": "quick-spec",
+      "description": "Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation. USE WHEN user needs to plan a feature, create tech-spec, or prepare implementation-ready documentation. Triggers on \"buat spec\", \"create tech spec\", \"plan feature\", \"specification\", or when user describes a feature to build without clear implementation plan.",
+      "category": "planning",
+      "type": "skill",
+      "path": "skills/quick-spec"
+    },
+    {
+      "name": "readme-expert",
+      "description": "Create comprehensive, accurate README.md files with anti-hallucination validation.",
+      "category": "documentation",
+      "type": "skill",
+      "path": "skills/readme-expert"
+    },
+    {
+      "name": "red-teaming",
+      "description": "Comprehensive red teaming methodology for both cybersecurity and AI/LLM systems. Use when conducting adversary emulation, vulnerability assessment, attack simulation, or security validation. Trigger on requests for penetration testing, threat modeling, security audits, MITRE ATT&CK operations, LLM safety testing, prompt injection attacks, or compliance validation (OWASP, NIST, TIBER, DORA, EU AI Act). Apply when users ask to \"test like an attacker\", \"red team our system\", \"validate security posture\", \"assess LLM vulnerabilities\", or \"simulate cyber attacks\". Includes planning frameworks, execution strategies, reporting templates, and progressive references to specialized attack techniques and tools.",
+      "category": "security",
+      "type": "skill",
+      "path": "skills/red-teaming"
+    },
+    {
+      "name": "releasing",
+      "description": "Automate the full release workflow: version bumping (major/minor/patch), changelog generation,",
+      "category": "deployment",
+      "type": "skill",
+      "path": "skills/releasing"
+    },
+    {
+      "name": "screenwriter",
+      "description": "Transform creative ideas into professional, production-ready screenplays optimized for AI video generation pipelines. Converts raw concepts into structured scene-by-scene narratives with rich visual descriptions, proper screenplay formatting, and XML-tagged output for seamless integration with image/video generation tools (imagine, arch-v).",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/screenwriter"
+    },
+    {
+      "name": "skillkit",
+      "description": "Research-driven toolkit for creating and validating skills and subagents with",
+      "category": "core",
+      "type": "skill",
+      "path": "skills/skillkit"
+    },
+    {
+      "name": "social-media-seo",
+      "description": "Optimize social media content for maximum discoverability and engagement using 2025-proven SEO strategies.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/social-media-seo"
+    },
+    {
+      "name": "storyteller",
+      "description": "Transform abstract/metaphorical narrative into concrete visual story structure.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/storyteller"
+    },
+    {
+      "name": "thread-pro",
+      "description": "Transform boring AI writing into viral threads with strong hooks and relatable voice.",
+      "category": "creative",
+      "type": "skill",
+      "path": "skills/thread-pro"
+    },
+    {
+      "name": "tinkering",
+      "description": "Safe experimentation framework for AI agents. Creates isolated sandbox",
+      "category": "experimentation",
+      "type": "skill",
+      "path": "skills/tinkering"
+    },
+    {
+      "name": "validate-plan",
+      "description": "Validate implementation plans against DRY, YAGNI, TDD principles and best practices. Use when reviewing development plans created by writing-plans or similar planning workflows to identify gaps, anti-patterns, and improvement opportunities before execution.",
+      "category": "planning",
+      "type": "skill",
+      "path": "skills/validate-plan"
+    },
+    {
+      "name": "verify-before-ship",
+      "description": "Enforce agent to complete all 7 production safety gates with evidence before any deployment. Use when about to deploy, push to production, merge a release branch, or ship any change to a live environment. Blocks rationalized shortcuts under time, authority, sunk-cost, or exhaustion pressure.",
+      "category": "deployment",
+      "type": "skill",
+      "path": "skills/verify-before-ship"
+    }
+  ],
+  "agents": [
+    {
+      "name": "creative-copywriter",
+      "description": "Intelligent creative copywriting orchestration for social media. Use this subagent when users need: (1) Hook creation with psychological triggers, (2) Carousel storytelling with swipe optimization, (3) Power word selection for specific emotions, (4) A/B test variations with different emotional angles, or (5) Complete content narratives with hooks and CTAs. Examples: <example>Context: User wants Instagram carousel hooks. user: 'Create hooks for my productivity carousel' assistant: 'I'll use the creative-copywriter subagent to query hook formulas and generate variations with different emotional triggers' <commentary>Since this requires querying hook-formulas.csv, power-words.csv, and synthesizing platform-specific optimization, use creative-copywriter for psychology-backed recommendations.</commentary></example> <example>Context: User needs swipe-worthy carousel structure. user: 'Help me structure a transformation carousel about my weight loss journey' assistant: 'Let me use the creative-copywriter subagent to recommend storytelling frameworks and swipe triggers' <commentary>Since this involves querying carousel-structures.csv, swipe-triggers.csv, and emotional-arcs.csv, use creative-copywriter proactively.</commentary></example> <example>Context: User wants multiple hook variations to test. user: 'Generate 3 different hooks for my business failure story' assistant: 'I'll engage the creative-copywriter subagent to create variations using different psychological triggers' <commentary>Since this requires multi-database querying and variation generation with different emotional angles, use creative-copywriter to provide psychology-backed options.</commentary></example>",
+      "type": "agent",
+      "path": "agents/creative-copywriter.md"
+    },
+    {
+      "name": "dario-amodei",
+      "description": "Use this agent when you need safety-first, deliberate decision-making with transparency, intellectual rigor, and democratic oversight principles. Examples: <example>Context: User deciding on AI model deployment timing. user: 'We have technical capability ready, should we launch now?' assistant: 'I'll engage the dario-amodei agent to evaluate safety-readiness beyond technical capability' <commentary>Since this requires assessing whether deployment safety research is sufficient, use the dario-amodei agent to provide perspective on responsible sequencing and risk mitigation.</commentary></example> <example>Context: User structuring AI governance. user: 'How should we organize decision-making authority for AI development?' assistant: 'Let me use the dario-amodei agent for governance design' <commentary>Since this involves balancing efficiency with oversight, use the dario-amodei agent to provide insights on distributed decision-making and accountability structures.</commentary></example> <example>Context: User navigating regulatory landscape. user: 'Should we support or oppose new AI regulations?' assistant: 'I'll engage the dario-amodei agent to evaluate regulatory engagement strategy' <commentary>Since this requires understanding responsible regulation advocacy, use the dario-amodei agent to provide perspective on how regulation can enable beneficial AI while managing risks.</commentary></example>",
+      "type": "agent",
+      "path": "agents/dario-amodei.md"
+    },
+    {
+      "name": "doc-simplifier",
+      "description": "Use this agent when you have functional documentation that's too verbose and needs condensing to improve clarity and reduce cognitive load. Examples: <example>Context: User has a technical research document that's 1200+ lines with repetitive sections. user:",
+      "type": "agent",
+      "path": "agents/doc-simplifier.md"
+    },
+    {
+      "name": "kotlin-pro",
+      "description": ">",
+      "type": "agent",
+      "path": "agents/kotlin-pro.md"
+    },
+    {
+      "name": "red-team",
+      "description": "<use_when>\\n  <description>Use this agent when you need systematic security testing, threat modeling, adversary emulation, vulnerability assessment, or security validation. Covers both traditional cybersecurity red teaming (MITRE ATT&CK, penetration testing) and modern AI/LLM security testing (prompt injection, jailbreaking, OWASP Top 10 LLM).</description>\\n  \\n  <example>\\n    <context>User is tasked with assessing organization's security posture and needs structured red team planning</context>\\n    <user>",
+      "type": "agent",
+      "path": "agents/red-team.md"
+    },
+    {
+      "name": "sam-altman",
+      "description": "Use this agent when you need velocity-first, market-driven decision-making with transformational leadership and aggressive execution strategies. Examples: <example>Context: User needs to decide on product launch timing. user: 'Should we delay the launch to add more safety features?' assistant: 'I'll engage the sam-altman agent to evaluate the velocity-risk tradeoff' <commentary>Since this involves balancing speed-to-market with risk management, use the sam-altman agent to provide perspective on aggressive execution while managing downsides.</commentary></example> <example>Context: User planning market entry strategy. user: 'How should we position ourselves against competitors in the AI space?' assistant: 'Let me use the sam-altman agent for competitive strategy guidance' <commentary>Since this requires understanding market dynamics and aggressive positioning, use the sam-altman agent to provide insights on capturing market share and building competitive moats.</commentary></example> <example>Context: User facing organizational governance decisions. user: 'Our board wants more control over product decisions' assistant: 'I'll engage the sam-altman agent to navigate governance dynamics' <commentary>Since this involves balancing stakeholder interests with execution velocity, use the sam-altman agent to provide perspective on maintaining decisional authority while managing relationships.</commentary></example>",
+      "type": "agent",
+      "path": "agents/sam-altman.md"
+    },
+    {
+      "name": "seo-manager",
+      "description": "Intelligent social media SEO content orchestration. Use this subagent when users need: (1) Platform-specific content optimization (Instagram, X/Twitter, Threads), (2) Multi-database querying for caption formulas, thread structures, viral patterns, (3) A/B test variation generation, (4) Evidence-based recommendations with metrics, or (5) Comprehensive SEO strategy for social media posts. Examples: <example>Context: User wants optimized Instagram caption for educational content. user: 'Create Instagram caption about SEO tips for high engagement' assistant: 'I'll use the seo-manager subagent to query our proven formula databases and generate optimized variations' <commentary>Since this requires querying caption-styles.csv, hook-formulas.csv, and synthesizing platform-specific optimization, use seo-manager for data-driven recommendations.</commentary></example> <example>Context: User needs viral Twitter thread structure. user: 'Help me structure a Twitter thread about content marketing' assistant: 'Let me use the seo-manager subagent to recommend proven thread architectures' <commentary>Since this involves querying thread-structures.csv and applying X/Twitter-specific SEO principles, use seo-manager proactively.</commentary></example> <example>Context: User wants multiple caption variations to A/B test. user: 'Generate 3 different Instagram captions for my product launch' assistant: 'I'll engage the seo-manager subagent to create variations from different proven styles' <commentary>Since this requires multi-database querying and variation generation, use seo-manager to provide evidence-based options.</commentary></example>",
+      "type": "agent",
+      "path": "agents/seo-manager.md"
+    }
+  ],
+  "generatedAt": "2026-03-14T18:10:24.737Z"
+}

package/src/banner.js

@@ -0,0 +1,10 @@
+export function printBanner(version) {
+  console.log(`
+\x1b[33m
+ ▄▄▄▄ ▄▄ ▄▄ ▄▄ ▄▄    ▄▄    ▄▄ ▄▄ ▄▄ ▄▄▄▄▄▄
+███▄▄ ██▄█▀ ██ ██    ██    ██▄█▀ ██   ██
+▄▄██▀ ██ ██ ██ ██▄▄▄ ██▄▄▄ ██ ██ ██   ██
+\x1b[0m
+\x1b[90mv${version} · Claude Code Skills Installer\x1b[0m
+`)
+}

package/src/cli.js

@@ -0,0 +1,30 @@
+import { intro, outro, cancel, isCancel, log } from '@clack/prompts'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { printBanner } from './banner.js'
+import { selectScope } from './scope.js'
+import { pickInstallables } from './picker.js'
+import { installSelected } from './install.js'
+import { checkForUpdates } from './update.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const { version } = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+
+export async function run() {
+  printBanner(version)
+  await checkForUpdates()
+
+  intro('SkillKit Installer')
+
+  const scope = await selectScope()
+  if (isCancel(scope)) { cancel('Cancelled.'); process.exit(0) }
+
+  const selected = await pickInstallables()
+  if (isCancel(selected)) { cancel('Cancelled.'); process.exit(0) }
+
+  const { installed } = await installSelected(selected, scope)
+
+  outro(`Done! ${installed} item(s) installed to ${scope.scope} scope.`)
+  log.info(`Restart Claude Code to pick up new skills.`)
+}

package/src/install.js

@@ -0,0 +1,53 @@
+import { cpSync, mkdirSync, existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { spinner, log } from '@clack/prompts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(__dirname, '..')
+
+export async function installSelected({ skills, agents }, { skillsDir, agentsDir }) {
+  // Validate inputs
+  if (!Array.isArray(skills)) throw new TypeError('skills must be an array')
+  if (!Array.isArray(agents)) throw new TypeError('agents must be an array')
+
+  const s = spinner()
+  s.start('Installing...')
+
+  let installed = 0
+  const skipped = []
+
+  for (const skill of skills) {
+    if (!skill.name || !skill.path) {
+      skipped.push(`invalid-skill-${installed}`)
+      continue
+    }
+    const src = join(PACKAGE_ROOT, skill.path)
+    const dest = join(skillsDir, skill.name)
+    if (!existsSync(src)) { skipped.push(skill.name); continue }
+    mkdirSync(dest, { recursive: true })
+    cpSync(src, dest, { recursive: true })
+    installed++
+  }
+
+  for (const agent of agents) {
+    if (!agent.name || !agent.path) {
+      skipped.push(`invalid-agent-${installed}`)
+      continue
+    }
+    const src = join(PACKAGE_ROOT, agent.path)
+    const dest = join(agentsDir, agent.name + '.md')
+    if (!existsSync(src)) { skipped.push(agent.name); continue }
+    mkdirSync(agentsDir, { recursive: true })
+    cpSync(src, dest)
+    installed++
+  }
+
+  s.stop(`Installed ${installed} item(s)`)
+
+  if (skipped.length > 0) {
+    log.warn(`Skipped (not found in package): ${skipped.join(', ')}`)
+  }
+
+  return { installed, skipped }
+}

package/src/install.test.js

@@ -0,0 +1,40 @@
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { installSelected } from './install.js'
+
+function createTempDir() {
+  return mkdtempSync(join(tmpdir(), 'skillkit-test-'))
+}
+
+test('installSelected validates skills is an array', async () => {
+  await assert.rejects(
+    installSelected({ skills: 'not-array', agents: [] }, { skillsDir: '/tmp', agentsDir: '/tmp' }),
+    /skills must be an array/
+  )
+})
+
+test('installSelected validates agents is an array', async () => {
+  await assert.rejects(
+    installSelected({ skills: [], agents: 'not-array' }, { skillsDir: '/tmp', agentsDir: '/tmp' }),
+    /agents must be an array/
+  )
+})
+
+test('installSelected skips invalid skill objects', async () => {
+  const skillsDir = createTempDir()
+  const agentsDir = createTempDir()
+
+  const result = await installSelected(
+    { skills: [{ name: null }, { name: 'valid', path: 'skills/valid' }], agents: [] },
+    { skillsDir, agentsDir }
+  )
+
+  assert.strictEqual(result.installed, 0)
+  assert.strictEqual(result.skipped.length, 2)
+
+  rmSync(skillsDir, { recursive: true })
+  rmSync(agentsDir, { recursive: true })
+})