skillsets 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,452 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { input, confirm, checkbox } from '@inquirer/prompts';
+import { existsSync, mkdirSync, copyFileSync, readdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+const SKILLSET_YAML_TEMPLATE = `schema_version: "1.0"
+
+# Identity
+name: "{{NAME}}"
+version: "1.0.0"
+description: "{{DESCRIPTION}}"
+
+author:
+  handle: "{{AUTHOR_HANDLE}}"
+  url: "{{AUTHOR_URL}}"
+
+# Verification
+verification:
+  production_url: "{{PRODUCTION_URL}}"
+  production_proof: "./PROOF.md"
+  audit_report: "./AUDIT_REPORT.md"
+
+# Discovery
+tags:
+{{TAGS}}
+
+compatibility:
+  claude_code_version: ">=1.0.0"
+  languages:
+    - "any"
+
+# Lifecycle
+status: "active"
+
+# Content
+entry_point: "./content/CLAUDE.md"
+`;
+const README_TEMPLATE = `# {{NAME}}
+
+{{DESCRIPTION}}
+
+## Installation
+
+\`\`\`bash
+npx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}
+\`\`\`
+
+## Usage
+
+[Describe how to use your skillset]
+
+## What's Included
+
+[List the key files and their purposes]
+
+## License
+
+[Your license]
+`;
+const PROOF_TEMPLATE = `# Production Proof
+
+## Overview
+
+This skillset has been verified in production.
+
+## Production URL
+
+{{PRODUCTION_URL}}
+
+## Evidence
+
+[Add screenshots, testimonials, or other evidence of production usage]
+
+## Projects Built
+
+[List projects or products built using this skillset]
+`;
+const AUDIT_SKILL_MD = `---
+name: skillset-audit
+description: Qualitative review of skillset content against Claude Code best practices. Evaluates all primitives (skills, agents, hooks, MCP, CLAUDE.md) for proper frontmatter, descriptions, and structure. Appends analysis to AUDIT_REPORT.md.
+---
+
+# Skillset Qualitative Audit
+
+## Task
+
+1. Verify \`AUDIT_REPORT.md\` shows "READY FOR SUBMISSION"
+2. Identify all primitives in \`content/\`:
+   - Skills: \`**/SKILL.md\`
+   - Agents: \`**/AGENT.md\` or \`**/*.agent.md\`
+   - Hooks: \`**/hooks.json\`
+   - MCP: \`**/.mcp.json\` or \`**/mcp.json\`
+   - CLAUDE.md: \`CLAUDE.md\` or \`.claude/settings.json\`
+3. Evaluate each against [CRITERIA.md](CRITERIA.md)
+4. Append findings to \`AUDIT_REPORT.md\`
+
+## Per-Primitive Evaluation
+
+### Skills
+- Frontmatter has \`name\` and \`description\`
+- Description includes trigger phrases ("Use when...")
+- Body under 500 lines
+- \`allowed-tools\` if restricting access
+- \`disable-model-invocation\` for side-effect commands
+
+### Agents
+- Description has \`<example>\` blocks
+- System prompt has role, responsibilities, process, output format
+- \`tools\` array if restricting access
+
+### Hooks
+- Valid JSON structure
+- Matchers are specific (not just \`.*\`)
+- Reasonable timeouts
+- Prompts are actionable
+
+### MCP
+- Uses \`\${CLAUDE_PLUGIN_ROOT}\` for paths
+- Env vars use \`\${VAR}\` syntax
+- No hardcoded secrets
+
+### CLAUDE.md
+- Under 300 lines (check line count)
+- Has WHAT/WHY/HOW sections
+- Uses \`file:line\` pointers, not code snippets
+- Progressive disclosure for large content
+
+## Output
+
+Append to \`AUDIT_REPORT.md\`:
+
+\`\`\`markdown
+---
+
+## Qualitative Review
+
+**Reviewed by:** Claude (Opus)
+**Date:** [ISO timestamp]
+
+### Primitives Found
+
+| Type | Count | Files |
+|------|-------|-------|
+| Skills | N | [list] |
+| Agents | N | [list] |
+| Hooks | N | [list] |
+| MCP | N | [list] |
+| CLAUDE.md | Y/N | [path] |
+
+### Issues
+
+[List each issue with file:line and specific fix needed]
+
+### Verdict
+
+**[APPROVED / NEEDS REVISION]**
+
+[If needs revision: prioritized list of must-fix items]
+\`\`\`
+`;
+const AUDIT_CRITERIA_MD = `# Evaluation Criteria
+
+Rubric for qualitative skillset review. Each primitive type has specific requirements.
+
+---
+
+## Skills (SKILL.md)
+
+Skills and slash commands are now unified. File at \`.claude/skills/[name]/SKILL.md\` creates \`/name\`.
+
+### Frontmatter Requirements
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| \`name\` | Yes | Becomes the \`/slash-command\`, lowercase with hyphens |
+| \`description\` | Yes | **Critical for discoverability** - Claude uses this to decide when to load |
+| \`version\` | No | Semver for tracking |
+| \`allowed-tools\` | No | Restricts tool access (e.g., \`Read, Write, Bash(git:*)\`) |
+| \`model\` | No | \`sonnet\`, \`opus\`, or \`haiku\` |
+| \`disable-model-invocation\` | No | \`true\` = only user can invoke (for side-effect commands) |
+| \`user-invocable\` | No | \`false\` = only Claude can invoke (background knowledge) |
+
+### Description Quality
+
+**GOOD:** Includes trigger phrases ("Use when reviewing PRs, checking vulnerabilities...")
+**POOR:** Vague ("Helps with code review")
+
+---
+
+## Agents (AGENT.md)
+
+### Frontmatter Requirements
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| \`name\` | Yes | Agent identifier |
+| \`description\` | Yes | **Must include \`<example>\` blocks** for reliable triggering |
+| \`model\` | No | \`inherit\`, \`sonnet\`, \`opus\`, \`haiku\` |
+| \`color\` | No | UI color hint |
+| \`tools\` | No | Array of allowed tools |
+
+### System Prompt (Body)
+
+- Clear role definition ("You are...")
+- Core responsibilities numbered
+- Process/workflow steps
+- Expected output format
+
+---
+
+## Hooks (hooks.json)
+
+### Event Types
+
+| Event | When | Use For |
+|-------|------|---------|
+| \`PreToolUse\` | Before tool executes | Validation, security checks |
+| \`PostToolUse\` | After tool completes | Feedback, logging |
+| \`Stop\` | Task completion | Quality gates, notifications |
+| \`SessionStart\` | Session begins | Context loading, env setup |
+
+### Quality Checks
+
+- Matchers are specific (avoid \`.*\` unless intentional)
+- Timeouts are reasonable
+- Prompts are concise and actionable
+
+---
+
+## MCP Servers (.mcp.json)
+
+### Quality Checks
+
+- Uses \`\${CLAUDE_PLUGIN_ROOT}\` for paths
+- Environment variables use \`\${VAR}\` syntax
+- Sensitive values reference env vars, not hardcoded
+
+---
+
+## CLAUDE.md
+
+### Critical Constraints
+
+- **Under 300 lines** (ideally <60)
+- LLMs follow ~150-200 instructions; Claude Code system prompt uses ~50
+
+### Required Content (WHAT, WHY, HOW)
+
+- **WHAT**: Tech stack, project structure, codebase map
+- **WHY**: Project purpose, component functions
+- **HOW**: Dev workflows, tools, testing, verification
+
+### What to Avoid
+
+- Task-specific instructions
+- Code style rules (use linters + hooks)
+- Code snippets (use \`file:line\` pointers)
+- Hardcoded dates/versions
+
+---
+
+## Verdict Rules
+
+- **APPROVED**: All primitives meet requirements, minor issues only
+- **NEEDS REVISION**: Missing required fields, poor descriptions, oversized files
+
+Priority:
+1. Missing/poor descriptions (affects discoverability)
+2. Oversized CLAUDE.md (degrades all instructions)
+3. Missing agent examples (unreliable triggering)
+`;
+function copyDirRecursive(src, dest) {
+    if (!existsSync(dest)) {
+        mkdirSync(dest, { recursive: true });
+    }
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export async function init(options) {
+    console.log(chalk.blue('\n📦 Initialize a new skillset submission\n'));
+    const cwd = process.cwd();
+    // Check if already initialized
+    if (existsSync(join(cwd, 'skillset.yaml'))) {
+        console.log(chalk.yellow('⚠ skillset.yaml already exists in this directory.'));
+        const overwrite = await confirm({
+            message: 'Overwrite existing files?',
+            default: false,
+        });
+        if (!overwrite) {
+            console.log(chalk.gray('Aborted.'));
+            return;
+        }
+    }
+    // Gather information
+    const name = await input({
+        message: 'Skillset name (alphanumeric, hyphens, underscores):',
+        validate: (value) => {
+            if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+                return 'Name must be alphanumeric with hyphens/underscores only';
+            }
+            if (value.length < 1 || value.length > 100) {
+                return 'Name must be 1-100 characters';
+            }
+            return true;
+        },
+    });
+    const description = await input({
+        message: 'Description (10-200 characters):',
+        validate: (value) => {
+            if (value.length < 10 || value.length > 200) {
+                return 'Description must be 10-200 characters';
+            }
+            return true;
+        },
+    });
+    const authorHandle = await input({
+        message: 'GitHub handle (e.g., @username):',
+        validate: (value) => {
+            if (!/^@[A-Za-z0-9_-]+$/.test(value)) {
+                return 'Handle must start with @ followed by alphanumeric characters';
+            }
+            return true;
+        },
+    });
+    const authorUrl = await input({
+        message: 'Author URL (GitHub profile or website):',
+        default: `https://github.com/${authorHandle.slice(1)}`,
+    });
+    const productionUrl = await input({
+        message: 'Production URL (live deployment, repo, or case study):',
+        validate: (value) => {
+            try {
+                new URL(value);
+                return true;
+            }
+            catch {
+                return 'Must be a valid URL';
+            }
+        },
+    });
+    const tagsInput = await input({
+        message: 'Tags (comma-separated, lowercase, e.g., sdlc,planning,multi-agent):',
+        validate: (value) => {
+            const tags = value.split(',').map((t) => t.trim());
+            if (tags.length < 1 || tags.length > 10) {
+                return 'Must have 1-10 tags';
+            }
+            for (const tag of tags) {
+                if (!/^[a-z0-9-]+$/.test(tag)) {
+                    return `Tag "${tag}" must be lowercase alphanumeric with hyphens only`;
+                }
+            }
+            return true;
+        },
+    });
+    const tags = tagsInput.split(',').map((t) => t.trim());
+    // Auto-detect existing files
+    const detectedFiles = [];
+    if (existsSync(join(cwd, '.claude'))) {
+        detectedFiles.push('.claude/');
+    }
+    if (existsSync(join(cwd, 'CLAUDE.md'))) {
+        detectedFiles.push('CLAUDE.md');
+    }
+    let filesToCopy = [];
+    if (detectedFiles.length > 0) {
+        console.log(chalk.green('\n✓ Detected existing skillset files:'));
+        detectedFiles.forEach((f) => console.log(`  - ${f}`));
+        filesToCopy = await checkbox({
+            message: 'Select files to copy to content/:',
+            choices: detectedFiles.map((f) => ({ name: f, value: f, checked: true })),
+        });
+    }
+    // Create structure
+    const spinner = ora('Creating skillset structure...').start();
+    try {
+        // Create content directory
+        mkdirSync(join(cwd, 'content'), { recursive: true });
+        // Copy selected files to content/
+        for (const file of filesToCopy) {
+            const src = join(cwd, file);
+            const dest = join(cwd, 'content', file);
+            if (file.endsWith('/')) {
+                // Directory
+                copyDirRecursive(src.slice(0, -1), dest.slice(0, -1));
+            }
+            else {
+                // File
+                copyFileSync(src, dest);
+            }
+        }
+        // Generate skillset.yaml
+        const tagsYaml = tags.map((t) => `  - "${t}"`).join('\n');
+        const skillsetYaml = SKILLSET_YAML_TEMPLATE
+            .replace('{{NAME}}', name)
+            .replace('{{DESCRIPTION}}', description)
+            .replace('{{AUTHOR_HANDLE}}', authorHandle)
+            .replace('{{AUTHOR_URL}}', authorUrl)
+            .replace('{{PRODUCTION_URL}}', productionUrl)
+            .replace('{{TAGS}}', tagsYaml);
+        writeFileSync(join(cwd, 'skillset.yaml'), skillsetYaml);
+        // Generate README.md (if not copying existing)
+        if (!existsSync(join(cwd, 'README.md'))) {
+            const readme = README_TEMPLATE
+                .replace(/\{\{NAME\}\}/g, name)
+                .replace(/\{\{DESCRIPTION\}\}/g, description)
+                .replace(/\{\{AUTHOR_HANDLE\}\}/g, authorHandle);
+            writeFileSync(join(cwd, 'README.md'), readme);
+        }
+        // Generate PROOF.md
+        const proof = PROOF_TEMPLATE.replace('{{PRODUCTION_URL}}', productionUrl);
+        writeFileSync(join(cwd, 'PROOF.md'), proof);
+        // Install skillset-audit skill to .claude/skills/
+        const skillDir = join(cwd, '.claude', 'skills', 'skillset-audit');
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, 'SKILL.md'), AUDIT_SKILL_MD);
+        writeFileSync(join(skillDir, 'CRITERIA.md'), AUDIT_CRITERIA_MD);
+        spinner.succeed('Skillset structure created');
+        // Summary
+        console.log(chalk.green('\n✓ Initialized skillset submission:\n'));
+        console.log('  skillset.yaml     - Manifest (edit as needed)');
+        console.log('  README.md         - Documentation');
+        console.log('  PROOF.md          - Production evidence (add details)');
+        console.log('  content/          - Installable files');
+        if (filesToCopy.length > 0) {
+            filesToCopy.forEach((f) => console.log(`    └── ${f}`));
+        }
+        else {
+            console.log('    └── (add your .claude/ and/or CLAUDE.md here)');
+        }
+        console.log('  .claude/skills/   - Audit skill installed');
+        console.log('    └── skillset-audit/');
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1. Edit PROOF.md with production evidence');
+        console.log('  2. Ensure content/ has your skillset files');
+        console.log('  3. Run: npx skillsets audit');
+        console.log('  4. Run: /skillset-audit (qualitative review)');
+    }
+    catch (error) {
+        spinner.fail('Failed to create structure');
+        throw error;
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,6 @@
+interface InstallOptions {
+    force?: boolean;
+    backup?: boolean;
+}
+export declare function install(skillsetId: string, options: InstallOptions): Promise<void>;
+export {};

package/dist/commands/install.js

@@ -0,0 +1,54 @@
+import degit from 'degit';
+import chalk from 'chalk';
+import ora from 'ora';
+import { detectConflicts, backupFiles } from '../lib/filesystem.js';
+import { verifyChecksums } from '../lib/checksum.js';
+import { REGISTRY_REPO } from '../lib/constants.js';
+export async function install(skillsetId, options) {
+    const spinner = ora(`Installing ${skillsetId}...`).start();
+    // Check for conflicts
+    const conflicts = await detectConflicts(process.cwd());
+    if (conflicts.length > 0 && !options.force && !options.backup) {
+        spinner.fail('Installation aborted');
+        console.log(chalk.yellow('\nExisting files detected:'));
+        conflicts.forEach((file) => console.log(`  - ${file}`));
+        console.log(chalk.cyan('\nUse one of these flags:'));
+        console.log('  --force   Overwrite existing files');
+        console.log('  --backup  Backup existing files before install');
+        return;
+    }
+    // Backup if requested
+    if (options.backup && conflicts.length > 0) {
+        spinner.text = 'Backing up existing files...';
+        await backupFiles(conflicts, process.cwd());
+    }
+    // Install using degit (extract content/ subdirectory)
+    spinner.text = 'Downloading skillset...';
+    const emitter = degit(`${REGISTRY_REPO}/skillsets/${skillsetId}/content`, {
+        cache: true,
+        force: true,
+        verbose: false,
+    });
+    await emitter.clone(process.cwd());
+    // Verify checksums
+    spinner.text = 'Verifying checksums...';
+    const result = await verifyChecksums(skillsetId, process.cwd());
+    if (!result.valid) {
+        spinner.fail('Checksum verification failed - files may be corrupted');
+        console.log(chalk.red('\nInstallation aborted due to checksum mismatch.'));
+        console.log(chalk.yellow('This could indicate:'));
+        console.log('  - Network issues during download');
+        console.log('  - Corrupted files in the registry');
+        console.log('  - Tampering with the downloaded content');
+        console.log(chalk.cyan('\nTo retry:'));
+        console.log(`  npx skillsets install ${skillsetId} --force`);
+        process.exit(1);
+    }
+    spinner.succeed(`Successfully installed ${skillsetId}`);
+    // Print next steps
+    console.log(chalk.green('\n✓ Installation complete!'));
+    console.log(chalk.gray('\nNext steps:'));
+    console.log('  1. Review CLAUDE.md for usage instructions');
+    console.log('  2. Customize .claude/skills/ for your project');
+    console.log('  3. Run: claude');
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,7 @@
+interface ListOptions {
+    limit?: string;
+    sort?: 'name' | 'stars' | 'recent';
+    json?: boolean;
+}
+export declare function list(options: ListOptions): Promise<void>;
+export {};

package/dist/commands/list.js

@@ -0,0 +1,72 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { fetchSearchIndex } from '../lib/api.js';
+export async function list(options) {
+    const spinner = ora('Fetching skillsets...').start();
+    try {
+        const index = await fetchSearchIndex();
+        spinner.stop();
+        let skillsets = [...index.skillsets];
+        // Sort
+        const sortBy = options.sort || 'name';
+        if (sortBy === 'stars') {
+            skillsets.sort((a, b) => b.stars - a.stars);
+        }
+        else if (sortBy === 'name') {
+            skillsets.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        // 'recent' would require a date field - skip for now
+        // Limit
+        const limit = parseInt(options.limit || '0', 10);
+        if (limit > 0) {
+            skillsets = skillsets.slice(0, limit);
+        }
+        // JSON output
+        if (options.json) {
+            console.log(JSON.stringify(skillsets, null, 2));
+            return;
+        }
+        // No results
+        if (skillsets.length === 0) {
+            console.log(chalk.yellow('No skillsets found in the registry.'));
+            console.log(chalk.gray('\nBe the first to contribute: npx skillsets init'));
+            return;
+        }
+        // Header
+        console.log(chalk.bold(`\n📦 Available Skillsets (${skillsets.length})\n`));
+        // Table header
+        console.log(chalk.gray(padEnd('NAME', 30) +
+            padEnd('AUTHOR', 20) +
+            padEnd('STARS', 8) +
+            'DESCRIPTION'));
+        console.log(chalk.gray('─'.repeat(100)));
+        // Rows
+        for (const s of skillsets) {
+            const name = padEnd(s.name, 30);
+            const author = padEnd(s.author.handle, 20);
+            const stars = padEnd(`★ ${s.stars}`, 8);
+            const desc = truncate(s.description, 40);
+            console.log(chalk.bold(name) +
+                chalk.gray(author) +
+                chalk.yellow(stars) +
+                desc);
+        }
+        console.log('');
+        console.log(chalk.gray(`Install: npx skillsets install <name>`));
+        console.log(chalk.gray(`Details: npx skillsets search <name>`));
+    }
+    catch (error) {
+        spinner.fail('Failed to fetch skillsets');
+        throw error;
+    }
+}
+function padEnd(str, len) {
+    if (str.length >= len)
+        return str.slice(0, len - 1) + ' ';
+    return str + ' '.repeat(len - str.length);
+}
+function truncate(str, len) {
+    if (str.length <= len)
+        return str;
+    return str.slice(0, len - 3) + '...';
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,6 @@
+interface SearchOptions {
+    tags?: string[];
+    limit?: string;
+}
+export declare function search(query: string, options: SearchOptions): Promise<void>;
+export {};

package/dist/commands/search.js

@@ -0,0 +1,38 @@
+import Fuse from 'fuse.js';
+import chalk from 'chalk';
+import { fetchSearchIndex } from '../lib/api.js';
+import { DEFAULT_SEARCH_LIMIT } from '../lib/constants.js';
+export async function search(query, options) {
+    console.log(chalk.blue(`Searching for: ${query}`));
+    // Fetch index from CDN
+    const index = await fetchSearchIndex();
+    // Filter by tags if provided
+    let filtered = index.skillsets;
+    if (options.tags && options.tags.length > 0) {
+        filtered = filtered.filter((skillset) => options.tags.some((tag) => skillset.tags.includes(tag)));
+    }
+    // Fuzzy search
+    const fuse = new Fuse(filtered, {
+        keys: ['name', 'description', 'tags', 'author.handle'],
+        threshold: 0.3,
+        includeScore: true,
+    });
+    const results = fuse.search(query);
+    const limit = parseInt(options.limit || DEFAULT_SEARCH_LIMIT.toString(), 10);
+    if (results.length === 0) {
+        console.log(chalk.yellow('No results found.'));
+        return;
+    }
+    console.log(chalk.green(`\nFound ${results.length} result(s):\n`));
+    results.slice(0, limit).forEach(({ item }) => {
+        console.log(chalk.bold(item.name));
+        console.log(`  ${item.description}`);
+        console.log(`  ${chalk.gray(`by ${item.author.handle}`)}`);
+        console.log(`  ${chalk.yellow(`★ ${item.stars}`)} ${chalk.gray(`• v${item.version}`)}`);
+        console.log(`  ${chalk.cyan(`npx skillsets install ${item.id}`)}`);
+        console.log();
+    });
+    if (results.length > limit) {
+        console.log(chalk.gray(`... and ${results.length - limit} more`));
+    }
+}

package/dist/commands/submit.d.ts

@@ -0,0 +1 @@
+export declare function submit(): Promise<void>;