skillsets 0.3.0 → 0.4.0

package/README.md

@@ -11,6 +11,7 @@ cli/
 │   ├── commands/          # Command implementations
 │   │   ├── list.ts
 │   │   ├── search.ts
+│   │   ├── view.ts
 │   │   ├── install.ts
 │   │   ├── init.ts
 │   │   ├── audit.ts
@@ -42,6 +43,7 @@ cli/
 |------|---------|---------------|
 | `list.ts` | Browse all skillsets with live stats | [Docs](./docs_cli/commands/list.md) |
 | `search.ts` | Fuzzy search by name, description, tags | [Docs](./docs_cli/commands/search.md) |
+| `view.ts` | View a skillset README before installing | [Docs](./docs_cli/commands/view.md) |
 | `install.ts` | Install skillset via degit + MCP warning + verify checksums | [Docs](./docs_cli/commands/install.md) |
 | `init.ts` | Scaffold new skillset for contribution | [Docs](./docs_cli/commands/init.md) |
 | `audit.ts` | Validate skillset + MCP servers before submission | [Docs](./docs_cli/commands/audit.md) |
@@ -58,5 +60,11 @@ cli/
 | `versions.ts` | Semver comparison | [Docs](./docs_cli/lib/versions.md) |
 | `validate-mcp.ts` | MCP server bidirectional validation | [Docs](./docs_cli/lib/validate-mcp.md) |
 
+### Types
+| File | Purpose | Documentation |
+|------|---------|---------------|
+| `index.ts` | SearchIndex, Skillset interfaces | [Docs](./docs_cli/types/index.md) |
+| `degit.d.ts` | TypeScript declarations for degit package | [Docs](./docs_cli/types/degit.d.md) |
+
 ## Related Documentation
 - [CLI Style Guide](../.claude/resources/cli_styleguide.md)

package/dist/commands/audit.js

@@ -16,13 +16,10 @@ const TEXT_EXTENSIONS = new Set([
     '.gitignore', '.editorconfig',
 ]);
 const SECRET_PATTERNS = [
-    { name: 'API Key', pattern: /api[_-]?key\s*[:=]\s*['"]?[a-zA-Z0-9]{20,}/gi },
-    { name: 'Password', pattern: /password\s*[:=]\s*['"]?[^'"\s]{8,}/gi },
-    { name: 'Secret', pattern: /secret\s*[:=]\s*['"]?[a-zA-Z0-9]{20,}/gi },
-    { name: 'Token', pattern: /token\s*[:=]\s*['"]?[a-zA-Z0-9]{20,}/gi },
     { name: 'AWS Key', pattern: /AKIA[0-9A-Z]{16}/g },
     { name: 'GitHub Token', pattern: /ghp_[a-zA-Z0-9]{36}/g },
     { name: 'OpenAI Key', pattern: /sk-[a-zA-Z0-9]{48}/g },
+    { name: 'Anthropic Key', pattern: /sk-ant-[a-zA-Z0-9_-]{20,}/g },
 ];
 function getAllFiles(dir, baseDir = dir) {
     const files = [];
@@ -64,7 +61,7 @@ function isBinaryFile(filePath) {
     }
 }
 function scanReadmeLinks(cwd) {
-    const readmePath = join(cwd, 'README.md');
+    const readmePath = join(cwd, 'content', 'README.md');
     if (!existsSync(readmePath))
         return [];
     const relativeLinks = [];
@@ -88,8 +85,8 @@ function scanForSecrets(dir) {
     const secrets = [];
     const files = getAllFiles(dir);
     for (const { path: filePath } of files) {
-        const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
-        if (!['.md', '.txt', '.json', '.yaml', '.yml', '.js', '.ts', '.py'].includes(ext))
+        const fullPath = join(dir, filePath);
+        if (isBinaryFile(fullPath))
             continue;
         if (filePath.includes('AUDIT_REPORT'))
             continue;
@@ -166,9 +163,8 @@ function formatSize(bytes) {
         return `${(bytes / 1024).toFixed(1)} KB`;
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
-function generateReport(results, cwd, enforceMcp = false) {
-    const timestamp = new Date().toISOString();
-    const allPassed = results.manifest.status === 'PASS' &&
+function isAuditPassing(results, enforceMcp) {
+    return results.manifest.status === 'PASS' &&
         results.requiredFiles.status === 'PASS' &&
         results.contentStructure.status === 'PASS' &&
         results.fileSize.status !== 'FAIL' &&
@@ -176,16 +172,20 @@ function generateReport(results, cwd, enforceMcp = false) {
         results.readmeLinks.status === 'PASS' &&
         results.versionCheck.status === 'PASS' &&
         (enforceMcp ? results.mcpServers.status === 'PASS' : true);
+}
+function statusIcon(status) {
+    if (status === 'PASS')
+        return '✓ PASS';
+    if (status === 'WARNING')
+        return '⚠ WARNING';
+    return '✗ FAIL';
+}
+function generateReport(results, cwd, enforceMcp = false) {
+    const timestamp = new Date().toISOString();
+    const allPassed = isAuditPassing(results, enforceMcp);
     const submissionType = results.isUpdate
         ? `Update (${results.existingVersion} → ${results.skillsetVersion})`
         : 'New submission';
-    const statusIcon = (status) => {
-        if (status === 'PASS')
-            return '✓ PASS';
-        if (status === 'WARNING')
-            return '⚠ WARNING';
-        return '✗ FAIL';
-    };
     let report = `# Audit Report
 
 **Generated:** ${timestamp}
@@ -332,16 +332,16 @@ export async function audit(options = {}) {
     }
     // 2. Required files
     spinner.text = 'Checking required files...';
-    const hasReadme = existsSync(join(cwd, 'README.md'));
     const hasContent = existsSync(join(cwd, 'content'));
+    const hasReadme = existsSync(join(cwd, 'content', 'README.md'));
     const hasSkillsetYaml = existsSync(join(cwd, 'skillset.yaml'));
     const missingFiles = [];
     if (!hasSkillsetYaml)
         missingFiles.push('skillset.yaml');
-    if (!hasReadme)
-        missingFiles.push('README.md');
     if (!hasContent)
         missingFiles.push('content/');
+    if (!hasReadme)
+        missingFiles.push('content/README.md');
     if (missingFiles.length === 0) {
         results.requiredFiles = { status: 'PASS', details: 'All present' };
     }
@@ -356,18 +356,18 @@ export async function audit(options = {}) {
     spinner.text = 'Verifying content structure...';
     const hasClaudeDir = existsSync(join(cwd, 'content', '.claude'));
     const hasClaudeMd = existsSync(join(cwd, 'content', 'CLAUDE.md'));
-    if (hasClaudeDir || hasClaudeMd) {
-        const found = [hasClaudeDir && '.claude/', hasClaudeMd && 'CLAUDE.md'].filter(Boolean);
+    if (hasClaudeDir && hasClaudeMd) {
         results.contentStructure = {
             status: 'PASS',
-            details: `Found: ${found.join(', ')}`,
+            details: 'Found: .claude/, CLAUDE.md',
         };
     }
     else {
+        const missing = [!hasClaudeDir && '.claude/', !hasClaudeMd && 'CLAUDE.md'].filter(Boolean);
         results.contentStructure = {
             status: 'FAIL',
-            details: 'No .claude/ or CLAUDE.md',
-            findings: 'content/ must contain either .claude/ directory or CLAUDE.md file',
+            details: `Missing: ${missing.join(', ')}`,
+            findings: 'content/ must contain both .claude/ directory and CLAUDE.md file',
         };
     }
     // 4. File size check
@@ -495,32 +495,30 @@ export async function audit(options = {}) {
     }
     spinner.succeed(options.check ? 'Validation complete' : 'Audit complete');
     // Summary
-    const allPassed = results.manifest.status === 'PASS' &&
-        results.requiredFiles.status === 'PASS' &&
-        results.contentStructure.status === 'PASS' &&
-        results.fileSize.status !== 'FAIL' &&
-        results.secrets.status === 'PASS' &&
-        results.readmeLinks.status === 'PASS' &&
-        results.versionCheck.status === 'PASS' &&
-        (options.check ? results.mcpServers.status === 'PASS' : true);
-    console.log('\n' + chalk.bold('Audit Summary:'));
-    console.log('');
-    const icon = (status) => {
+    const allPassed = isAuditPassing(results, !!options.check);
+    const colorIcon = (status) => {
         if (status === 'PASS')
             return chalk.green('✓');
         if (status === 'WARNING')
             return chalk.yellow('⚠');
         return chalk.red('✗');
     };
-    console.log(`  ${icon(results.manifest.status)} Manifest: ${results.manifest.details}`);
-    console.log(`  ${icon(results.requiredFiles.status)} Required Files: ${results.requiredFiles.details}`);
-    console.log(`  ${icon(results.contentStructure.status)} Content Structure: ${results.contentStructure.details}`);
-    console.log(`  ${icon(results.fileSize.status)} File Sizes: ${results.fileSize.details}`);
-    console.log(`  ${icon(results.binary.status)} Binary Files: ${results.binary.details}`);
-    console.log(`  ${icon(results.secrets.status)} Secrets: ${results.secrets.details}`);
-    console.log(`  ${icon(results.readmeLinks.status)} README Links: ${results.readmeLinks.details}`);
-    console.log(`  ${icon(results.versionCheck.status)} Version: ${results.versionCheck.details}`);
-    console.log(`  ${icon(results.mcpServers.status)} MCP Servers: ${results.mcpServers.details}`);
+    const checks = [
+        [results.manifest, 'Manifest'],
+        [results.requiredFiles, 'Required Files'],
+        [results.contentStructure, 'Content Structure'],
+        [results.fileSize, 'File Sizes'],
+        [results.binary, 'Binary Files'],
+        [results.secrets, 'Secrets'],
+        [results.readmeLinks, 'README Links'],
+        [results.versionCheck, 'Version'],
+        [results.mcpServers, 'MCP Servers'],
+    ];
+    console.log('\n' + chalk.bold('Audit Summary:'));
+    console.log('');
+    for (const [result, label] of checks) {
+        console.log(`  ${colorIcon(result.status)} ${label}: ${result.details}`);
+    }
     console.log('');
     if (allPassed) {
         console.log(chalk.green('✓ READY FOR SUBMISSION'));

package/dist/commands/init.js

@@ -4,7 +4,9 @@ import { input, confirm, checkbox } from '@inquirer/prompts';
 import { existsSync, mkdirSync, copyFileSync, readdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import degit from 'degit';
+import { execSync } from 'child_process';
 const SKILLSET_YAML_TEMPLATE = `schema_version: "1.0"
+batch_id: "{{BATCH_ID}}"
 
 # Identity
 name: "{{NAME}}"
@@ -95,6 +97,48 @@ function copyDirRecursive(src, dest) {
 }
 export async function init(options) {
     console.log(chalk.blue('\n📦 Initialize a new skillset submission\n'));
+    // 1. Verify gh CLI is available and authenticated
+    try {
+        execSync('gh auth status', { stdio: 'pipe' });
+    }
+    catch {
+        console.error(chalk.red('Error: gh CLI not authenticated.'));
+        console.error('Install: https://cli.github.com');
+        console.error('Then run: gh auth login');
+        process.exit(1);
+    }
+    // 2. Get GitHub user info (verified identity)
+    let login;
+    let id;
+    try {
+        const userJson = execSync('gh api user', { encoding: 'utf-8' });
+        const userData = JSON.parse(userJson);
+        login = userData.login;
+        id = userData.id;
+    }
+    catch (error) {
+        console.error(chalk.red('Error: Failed to get GitHub user info.'));
+        console.error('Please ensure gh CLI is properly authenticated.');
+        process.exit(1);
+    }
+    // 3. Look up reservation
+    let batchId;
+    try {
+        const res = await fetch(`https://skillsets.cc/api/reservations/lookup?githubId=${encodeURIComponent(String(id))}`);
+        const lookupData = await res.json();
+        if (!lookupData.batchId) {
+            console.error(chalk.red('No active reservation found.'));
+            console.error('Visit https://skillsets.cc to claim a slot first.');
+            process.exit(1);
+        }
+        batchId = lookupData.batchId;
+        console.log(chalk.green(`\nReservation found: ${batchId}`));
+    }
+    catch (error) {
+        console.error(chalk.red('Error: Failed to look up reservation.'));
+        console.error('Please check your network connection and try again.');
+        process.exit(1);
+    }
     const cwd = process.cwd();
     // Check if already initialized
     if (existsSync(join(cwd, 'skillset.yaml'))) {
@@ -132,6 +176,7 @@ export async function init(options) {
     });
     const authorHandle = await input({
         message: 'GitHub handle (e.g., @username):',
+        default: `@${login}`,
         validate: (value) => {
             if (!/^@[A-Za-z0-9_-]+$/.test(value)) {
                 return 'Handle must start with @ followed by alphanumeric characters';
@@ -142,6 +187,15 @@ export async function init(options) {
     const authorUrl = await input({
         message: 'Author URL (GitHub profile or website):',
         default: `https://github.com/${authorHandle.slice(1)}`,
+        validate: (value) => {
+            try {
+                new URL(value);
+                return true;
+            }
+            catch {
+                return 'Must be a valid URL';
+            }
+        },
     });
     const productionUrl = await input({
         message: 'Production URL (live deployment, repo, or case study):',
@@ -172,13 +226,11 @@ export async function init(options) {
     });
     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');
-    }
+    const candidateFiles = ['CLAUDE.md', 'README.md', '.claude/', '.mcp.json', 'docker/'];
+    const detectedFiles = candidateFiles.filter((f) => {
+        const checkPath = f.endsWith('/') ? f.slice(0, -1) : f;
+        return existsSync(join(cwd, checkPath));
+    });
     let filesToCopy = [];
     if (detectedFiles.length > 0) {
         console.log(chalk.green('\n✓ Detected existing skillset files:'));
@@ -209,6 +261,7 @@ export async function init(options) {
         // Generate skillset.yaml
         const tagsYaml = tags.map((t) => `  - "${t}"`).join('\n');
         const skillsetYaml = SKILLSET_YAML_TEMPLATE
+            .replace('{{BATCH_ID}}', batchId)
             .replace('{{NAME}}', name)
             .replace('{{DESCRIPTION}}', description)
             .replace('{{AUTHOR_HANDLE}}', authorHandle)
@@ -216,13 +269,13 @@ export async function init(options) {
             .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'))) {
+        // Generate content/README.md (if not copying existing)
+        if (!existsSync(join(cwd, 'content', '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);
+            writeFileSync(join(cwd, 'content', 'README.md'), readme);
         }
         // Generate PROOF.md
         const proof = PROOF_TEMPLATE.replace('{{PRODUCTION_URL}}', productionUrl);
@@ -240,9 +293,9 @@ export async function init(options) {
         // 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');
+        console.log('    ├── README.md   - Documentation');
         if (filesToCopy.length > 0) {
             filesToCopy.forEach((f) => console.log(`    └── ${f}`));
         }

package/dist/commands/install.js

@@ -6,6 +6,10 @@ import { detectConflicts, backupFiles } from '../lib/filesystem.js';
 import { verifyChecksums } from '../lib/checksum.js';
 import { fetchSkillsetMetadata } from '../lib/api.js';
 import { REGISTRY_REPO, DOWNLOADS_URL } from '../lib/constants.js';
+import { mkdtemp, rm, cp, readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
 function formatMcpWarning(mcpServers, skillsetId) {
     let output = chalk.yellow('\n⚠  This skillset includes MCP servers:\n');
     const nativeServers = mcpServers.filter(s => s.type !== 'docker');
@@ -36,6 +40,13 @@ function formatMcpWarning(mcpServers, skillsetId) {
 }
 export async function install(skillsetId, options) {
     const spinner = ora(`Installing ${skillsetId}...`).start();
+    // Validate skillsetId format
+    if (!/^@[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+$/.test(skillsetId)) {
+        spinner.fail('Invalid skillset ID');
+        console.log(chalk.red('\nExpected format: @author/name'));
+        console.log(chalk.gray('Example: @supercollectible/Valence'));
+        return;
+    }
     // Check for conflicts
     const conflicts = await detectConflicts(process.cwd());
     if (conflicts.length > 0 && !options.force && !options.backup) {
@@ -53,6 +64,7 @@ export async function install(skillsetId, options) {
         await backupFiles(conflicts, process.cwd());
     }
     // Fetch metadata and check for MCP servers BEFORE degit
+    let metadataFetchFailed = false;
     spinner.text = 'Fetching skillset metadata...';
     try {
         const metadata = await fetchSkillsetMetadata(skillsetId);
@@ -79,30 +91,76 @@ export async function install(skillsetId, options) {
         }
     }
     catch {
-        // If metadata fetch fails, continue without MCP check
-        // (registry might be down, don't block install)
+        // Metadata fetch failed — flag for post-install content check
+        metadataFetchFailed = true;
     }
-    // Install using degit (extract content/ subdirectory)
+    // Install to temp directory first (verify before writing to cwd)
     spinner.text = 'Downloading skillset...';
-    const emitter = degit(`${REGISTRY_REPO}/skillsets/${skillsetId}/content`, {
-        cache: false,
-        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);
+    const tempDir = await mkdtemp(join(tmpdir(), 'skillsets-'));
+    try {
+        const emitter = degit(`${REGISTRY_REPO}/skillsets/${skillsetId}/content`, {
+            cache: false,
+            force: true,
+            verbose: false,
+        });
+        await emitter.clone(tempDir);
+        // Post-install MCP check: if metadata fetch failed, inspect downloaded content
+        if (metadataFetchFailed) {
+            const hasMcpJson = existsSync(join(tempDir, '.mcp.json'));
+            const hasClaudeSettings = existsSync(join(tempDir, '.claude', 'settings.json'));
+            if (hasMcpJson || hasClaudeSettings) {
+                spinner.stop();
+                if (!process.stdin.isTTY && !options.acceptMcp) {
+                    console.log(chalk.red('This skillset includes MCP servers. Use --accept-mcp to install in non-interactive environments.'));
+                    await rm(tempDir, { recursive: true, force: true });
+                    process.exit(1);
+                    return;
+                }
+                if (!options.acceptMcp) {
+                    console.log(chalk.yellow('\n⚠  This skillset may include MCP servers (metadata unavailable for pre-check).'));
+                    console.log(chalk.cyan(`\n  Review before installing:\n    https://github.com/skillsets-cc/main/tree/main/skillsets/${skillsetId}/content\n`));
+                    const accepted = await confirm({
+                        message: 'Continue installation?',
+                        default: false,
+                    });
+                    if (!accepted) {
+                        console.log(chalk.gray('\nInstallation cancelled.'));
+                        await rm(tempDir, { recursive: true, force: true });
+                        return;
+                    }
+                }
+                spinner.start('Verifying checksums...');
+            }
+        }
+        // Verify checksums against temp directory
+        spinner.text = 'Verifying checksums...';
+        const result = await verifyChecksums(skillsetId, tempDir);
+        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`);
+            await rm(tempDir, { recursive: true, force: true });
+            process.exit(1);
+        }
+        // Checksums valid — move verified content to cwd
+        spinner.text = 'Installing verified content...';
+        const entries = await readdir(tempDir, { withFileTypes: true });
+        for (const entry of entries) {
+            await cp(join(tempDir, entry.name), join(process.cwd(), entry.name), {
+                recursive: true,
+                force: true,
+            });
+        }
+        await rm(tempDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        throw error;
     }
     spinner.succeed(`Successfully installed ${skillsetId}`);
     // Track download (non-blocking, silent fail)

package/dist/commands/submit.js

@@ -7,7 +7,7 @@ import yaml from 'js-yaml';
 import { tmpdir } from 'os';
 import { fetchSkillsetMetadata } from '../lib/api.js';
 import { compareVersions } from '../lib/versions.js';
-const REGISTRY_REPO = 'skillsets-cc/main';
+import { REGISTRY_REPO } from '../lib/constants.js';
 const REGISTRY_URL = `https://github.com/${REGISTRY_REPO}`;
 function checkGhCli() {
     try {
@@ -116,7 +116,7 @@ export async function submit() {
     }
     console.log(chalk.green('✓ Audit report passing'));
     // 6. Check required files
-    const requiredFiles = ['skillset.yaml', 'README.md', 'PROOF.md', 'AUDIT_REPORT.md', 'content'];
+    const requiredFiles = ['skillset.yaml', 'PROOF.md', 'AUDIT_REPORT.md', 'content'];
     for (const file of requiredFiles) {
         if (!existsSync(join(cwd, file))) {
             console.log(chalk.red(`✗ Missing required: ${file}`));
@@ -181,7 +181,7 @@ export async function submit() {
         mkdirSync(skillsetDir, { recursive: true });
         // Copy files
         spinner.text = 'Copying skillset files...';
-        const filesToCopy = ['skillset.yaml', 'README.md', 'PROOF.md', 'AUDIT_REPORT.md', 'content'];
+        const filesToCopy = ['skillset.yaml', 'PROOF.md', 'AUDIT_REPORT.md', 'content'];
         for (const file of filesToCopy) {
             const src = join(cwd, file);
             const dest = join(skillsetDir, file);

package/dist/commands/view.d.ts

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

package/dist/commands/view.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { fetchSkillsetMetadata } from '../lib/api.js';
+import { GITHUB_RAW_BASE } from '../lib/constants.js';
+export async function view(skillsetId) {
+    const spinner = ora('Fetching README...').start();
+    const metadata = await fetchSkillsetMetadata(skillsetId);
+    if (!metadata) {
+        spinner.fail(`Skillset '${skillsetId}' not found`);
+        throw new Error(`Skillset '${skillsetId}' not found`);
+    }
+    const [namespace, name] = skillsetId.split('/');
+    const encodedPath = encodeURIComponent(namespace) + '/' + encodeURIComponent(name);
+    const url = `${GITHUB_RAW_BASE}/skillsets/${encodedPath}/content/README.md`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        spinner.fail(`Could not fetch README for '${skillsetId}'`);
+        throw new Error(`Could not fetch README for '${skillsetId}'`);
+    }
+    spinner.stop();
+    const readme = await response.text();
+    console.log();
+    console.log(chalk.bold(`  ${skillsetId}`));
+    console.log();
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    console.log();
+    console.log(readme);
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 import { program } from 'commander';
 import { search } from './commands/search.js';
 import { list } from './commands/list.js';
+import { view } from './commands/view.js';
 import { install } from './commands/install.js';
 import { init } from './commands/init.js';
 import { audit } from './commands/audit.js';
@@ -40,6 +41,18 @@ program
         handleError(error);
     }
 });
+program
+    .command('view')
+    .description('View a skillset README before installing')
+    .argument('<skillsetId>', 'Skillset ID (e.g., @user/skillset-name)')
+    .action(async (skillsetId) => {
+    try {
+        await view(skillsetId);
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
 program
     .command('install')
     .description('Install a skillset to the current directory')

package/dist/lib/checksum.js

@@ -6,7 +6,7 @@ import { fetchSkillsetMetadata } from './api.js';
  * Computes SHA-256 checksum for a file.
  */
 export async function computeFileChecksum(filePath) {
-    const content = await fs.readFile(filePath, 'utf-8');
+    const content = await fs.readFile(filePath);
     return crypto.createHash('sha256').update(content).digest('hex');
 }
 /**

package/dist/lib/constants.d.ts

@@ -3,6 +3,7 @@ export declare const SEARCH_INDEX_URL = "https://skillsets.cc/search-index.json"
 export declare const STATS_URL = "https://skillsets.cc/api/stats/counts";
 export declare const DOWNLOADS_URL = "https://skillsets.cc/api/downloads";
 export declare const REGISTRY_REPO = "skillsets-cc/main";
+export declare const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/skillsets-cc/main/main";
 export declare const CACHE_TTL_MS: number;
 export declare const DEFAULT_SEARCH_LIMIT = 10;
 export declare const BACKUP_DIR_NAME = ".claude.backup";

package/dist/lib/constants.js

@@ -3,6 +3,7 @@ export const SEARCH_INDEX_URL = `${CDN_BASE_URL}/search-index.json`;
 export const STATS_URL = `${CDN_BASE_URL}/api/stats/counts`;
 export const DOWNLOADS_URL = `${CDN_BASE_URL}/api/downloads`;
 export const REGISTRY_REPO = 'skillsets-cc/main';
+export const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/${REGISTRY_REPO}/main`;
 export const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 export const DEFAULT_SEARCH_LIMIT = 10;
 export const BACKUP_DIR_NAME = '.claude.backup';

package/dist/lib/validate-mcp.js

@@ -49,22 +49,18 @@ export function validateMcpServers(skillsetDir) {
     return { valid: errors.length === 0, errors };
 }
 /**
- * Collect MCP servers from content files (.mcp.json, .claude/settings.json, docker configs)
+ * Parse native MCP servers from a JSON file containing an `mcpServers` key.
+ * Deduplicates against existing servers by name.
  */
-function collectContentServers(skillsetDir, errors) {
-    const servers = [];
-    const contentDir = join(skillsetDir, 'content');
-    if (!existsSync(contentDir)) {
-        return servers;
-    }
-    // 1. Check .mcp.json
-    const mcpJsonPath = join(contentDir, '.mcp.json');
-    if (existsSync(mcpJsonPath)) {
-        try {
-            const content = readFileSync(mcpJsonPath, 'utf-8');
-            const data = JSON.parse(content);
-            if (data.mcpServers && typeof data.mcpServers === 'object') {
-                for (const [name, config] of Object.entries(data.mcpServers)) {
+function parseNativeServersFromJson(filePath, servers, errors) {
+    if (!existsSync(filePath))
+        return;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        if (data.mcpServers && typeof data.mcpServers === 'object') {
+            for (const [name, config] of Object.entries(data.mcpServers)) {
+                if (!servers.some(s => s.name === name && s.source === 'native')) {
                     servers.push({
                         name,
                         source: 'native',
@@ -75,58 +71,29 @@ function collectContentServers(skillsetDir, errors) {
                 }
             }
         }
-        catch (error) {
-            errors.push(`Failed to parse .mcp.json: ${error.message}`);
-        }
     }
-    // 2. Check .claude/settings.json
-    const settingsPath = join(contentDir, '.claude', 'settings.json');
-    if (existsSync(settingsPath)) {
-        try {
-            const content = readFileSync(settingsPath, 'utf-8');
-            const data = JSON.parse(content);
-            if (data.mcpServers && typeof data.mcpServers === 'object') {
-                for (const [name, config] of Object.entries(data.mcpServers)) {
-                    // Avoid duplicates (same name might be in both files)
-                    if (!servers.some(s => s.name === name && s.source === 'native')) {
-                        servers.push({
-                            name,
-                            source: 'native',
-                            command: config.command,
-                            args: config.args,
-                            url: config.url,
-                        });
-                    }
-                }
-            }
-        }
-        catch (error) {
-            errors.push(`Failed to parse .claude/settings.json: ${error.message}`);
-        }
+    catch (error) {
+        const label = filePath.split('/').slice(-2).join('/');
+        errors.push(`Failed to parse ${label}: ${error.message}`);
     }
-    // 3. Check .claude/settings.local.json
-    const settingsLocalPath = join(contentDir, '.claude', 'settings.local.json');
-    if (existsSync(settingsLocalPath)) {
-        try {
-            const content = readFileSync(settingsLocalPath, 'utf-8');
-            const data = JSON.parse(content);
-            if (data.mcpServers && typeof data.mcpServers === 'object') {
-                for (const [name, config] of Object.entries(data.mcpServers)) {
-                    if (!servers.some(s => s.name === name && s.source === 'native')) {
-                        servers.push({
-                            name,
-                            source: 'native',
-                            command: config.command,
-                            args: config.args,
-                            url: config.url,
-                        });
-                    }
-                }
-            }
-        }
-        catch (error) {
-            errors.push(`Failed to parse .claude/settings.local.json: ${error.message}`);
-        }
+}
+/**
+ * Collect MCP servers from content files (.mcp.json, .claude/settings.json, docker configs)
+ */
+function collectContentServers(skillsetDir, errors) {
+    const servers = [];
+    const contentDir = join(skillsetDir, 'content');
+    if (!existsSync(contentDir)) {
+        return servers;
+    }
+    // Native MCP server sources (order matters for dedup: first found wins)
+    const nativeJsonPaths = [
+        join(contentDir, '.mcp.json'),
+        join(contentDir, '.claude', 'settings.json'),
+        join(contentDir, '.claude', 'settings.local.json'),
+    ];
+    for (const jsonPath of nativeJsonPaths) {
+        parseNativeServersFromJson(jsonPath, servers, errors);
     }
     // 4. Check docker/**/*.yaml and docker/**/*.yml for mcp_servers key
     const dockerDir = join(contentDir, 'docker');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsets",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI tool for discovering and installing verified skillsets",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc && node dist/index.js",
-    "test": "vitest",
+    "test": "vitest --run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },