skillsets 0.2.5 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ cli/
 │   │   ├── constants.ts
 │   │   ├── errors.ts
 │   │   ├── filesystem.ts
+│   │   ├── validate-mcp.ts
 │   │   └── versions.ts
 │   └── types/
 │       └── index.ts
@@ -41,9 +42,9 @@ 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) |
-| `install.ts` | Install skillset via degit + verify checksums | [Docs](./docs_cli/commands/install.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 before submission | [Docs](./docs_cli/commands/audit.md) |
+| `audit.ts` | Validate skillset + MCP servers before submission | [Docs](./docs_cli/commands/audit.md) |
 | `submit.ts` | Open PR to registry | [Docs](./docs_cli/commands/submit.md) |
 
 ### Lib
@@ -55,6 +56,7 @@ cli/
 | `errors.ts` | Error types | [Docs](./docs_cli/lib/errors.md) |
 | `filesystem.ts` | File utilities | [Docs](./docs_cli/lib/filesystem.md) |
 | `versions.ts` | Semver comparison | [Docs](./docs_cli/lib/versions.md) |
+| `validate-mcp.ts` | MCP server bidirectional validation | [Docs](./docs_cli/lib/validate-mcp.md) |
 
 ## Related Documentation
 - [CLI Style Guide](../.claude/resources/cli_styleguide.md)

package/dist/commands/audit.d.ts

@@ -1 +1,5 @@
-export declare function audit(): Promise<void>;
+interface AuditOptions {
+    check?: boolean;
+}
+export declare function audit(options?: AuditOptions): Promise<void>;
+export {};

package/dist/commands/audit.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, openSyn
 import { join, relative } from 'path';
 import yaml from 'js-yaml';
 import { fetchSkillsetMetadata } from '../lib/api.js';
+import { validateMcpServers } from '../lib/validate-mcp.js';
 import { compareVersions } from '../lib/versions.js';
 const MAX_FILE_SIZE = 1048576; // 1MB
 const TEXT_EXTENSIONS = new Set([
@@ -165,7 +166,7 @@ function formatSize(bytes) {
         return `${(bytes / 1024).toFixed(1)} KB`;
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
-function generateReport(results, cwd) {
+function generateReport(results, cwd, enforceMcp = false) {
     const timestamp = new Date().toISOString();
     const allPassed = results.manifest.status === 'PASS' &&
         results.requiredFiles.status === 'PASS' &&
@@ -173,7 +174,8 @@ function generateReport(results, cwd) {
         results.fileSize.status !== 'FAIL' &&
         results.secrets.status === 'PASS' &&
         results.readmeLinks.status === 'PASS' &&
-        results.versionCheck.status === 'PASS';
+        results.versionCheck.status === 'PASS' &&
+        (enforceMcp ? results.mcpServers.status === 'PASS' : true);
     const submissionType = results.isUpdate
         ? `Update (${results.existingVersion} → ${results.skillsetVersion})`
         : 'New submission';
@@ -205,6 +207,7 @@ function generateReport(results, cwd) {
 | Secret Detection | ${statusIcon(results.secrets.status)} | ${results.secrets.details} |
 | README Links | ${statusIcon(results.readmeLinks.status)} | ${results.readmeLinks.details} |
 | Version Check | ${statusIcon(results.versionCheck.status)} | ${results.versionCheck.details} |
+| MCP Servers | ${statusIcon(results.mcpServers.status)} | ${results.mcpServers.details} |
 
 ---
 
@@ -249,6 +252,10 @@ ${results.readmeLinks.findings || 'All links use valid GitHub URLs.'}
 
 ${results.relativeLinks.length > 0 ? '**Relative Links Found:**\n' + results.relativeLinks.map(l => `- Line ${l.line}: ${l.link}`).join('\n') : ''}
 
+### 8. MCP Server Validation
+
+${results.mcpServers.findings || 'MCP server declarations are consistent between content and manifest.'}
+
 ---
 
 ## File Inventory
@@ -287,7 +294,7 @@ ${allPassed
 `;
     return report;
 }
-export async function audit() {
+export async function audit(options = {}) {
     const spinner = ora('Auditing skillset...').start();
     const cwd = process.cwd();
     const results = {
@@ -299,6 +306,7 @@ export async function audit() {
         secrets: { status: 'PASS', details: '' },
         versionCheck: { status: 'PASS', details: '' },
         readmeLinks: { status: 'PASS', details: '' },
+        mcpServers: { status: 'PASS', details: '' },
         isUpdate: false,
         files: [],
         largeFiles: [],
@@ -458,11 +466,34 @@ export async function audit() {
     else {
         results.versionCheck = { status: 'PASS', details: 'Skipped (no manifest)' };
     }
+    // 9. MCP server validation
+    spinner.text = 'Validating MCP servers...';
+    const mcpResult = validateMcpServers(cwd);
+    if (mcpResult.valid) {
+        results.mcpServers = { status: 'PASS', details: 'MCP declarations valid' };
+    }
+    else if (options.check) {
+        results.mcpServers = {
+            status: 'FAIL',
+            details: `${mcpResult.errors.length} MCP error(s)`,
+            findings: mcpResult.errors.map(e => `- ${e}`).join('\n'),
+        };
+    }
+    else {
+        results.mcpServers = {
+            status: 'WARNING',
+            details: 'Pending qualitative review',
+            findings: 'MCP servers detected in content. The `/audit-skill` will populate `skillset.yaml` and CI will re-validate.\n\n' +
+                mcpResult.errors.map(e => `- ${e}`).join('\n'),
+        };
+    }
     // Generate report
     spinner.text = 'Generating audit report...';
-    const report = generateReport(results, cwd);
-    writeFileSync(join(cwd, 'AUDIT_REPORT.md'), report);
-    spinner.succeed('Audit complete');
+    const report = generateReport(results, cwd, options.check);
+    if (!options.check) {
+        writeFileSync(join(cwd, 'AUDIT_REPORT.md'), report);
+    }
+    spinner.succeed(options.check ? 'Validation complete' : 'Audit complete');
     // Summary
     const allPassed = results.manifest.status === 'PASS' &&
         results.requiredFiles.status === 'PASS' &&
@@ -470,7 +501,8 @@ export async function audit() {
         results.fileSize.status !== 'FAIL' &&
         results.secrets.status === 'PASS' &&
         results.readmeLinks.status === 'PASS' &&
-        results.versionCheck.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) => {
@@ -488,15 +520,23 @@ export async function audit() {
     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}`);
     console.log('');
     if (allPassed) {
         console.log(chalk.green('✓ READY FOR SUBMISSION'));
-        console.log(chalk.gray('\nGenerated: AUDIT_REPORT.md'));
-        console.log(chalk.cyan('\nNext: npx skillsets submit'));
+        if (!options.check) {
+            console.log(chalk.gray('\nGenerated: AUDIT_REPORT.md'));
+            console.log(chalk.cyan('\nNext: npx skillsets submit'));
+        }
     }
     else {
         console.log(chalk.red('✗ NOT READY - Fix issues above'));
-        console.log(chalk.gray('\nGenerated: AUDIT_REPORT.md'));
-        console.log(chalk.cyan('\nRe-run after fixes: npx skillsets audit'));
+        if (!options.check) {
+            console.log(chalk.gray('\nGenerated: AUDIT_REPORT.md'));
+            console.log(chalk.cyan('\nRe-run after fixes: npx skillsets audit'));
+        }
+        if (options.check) {
+            process.exit(1);
+        }
     }
 }

package/dist/commands/init.js

@@ -3,6 +3,7 @@ import ora from 'ora';
 import { input, confirm, checkbox } from '@inquirer/prompts';
 import { existsSync, mkdirSync, copyFileSync, readdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import degit from 'degit';
 const SKILLSET_YAML_TEMPLATE = `schema_version: "1.0"
 
 # Identity
@@ -76,200 +77,6 @@ This skillset has been verified in production.
 
 [List projects or products built using this skillset]
 `;
-const AUDIT_SKILL_MD = `---
-name: audit-skill
-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 });
@@ -420,11 +227,15 @@ export async function init(options) {
         // Generate PROOF.md
         const proof = PROOF_TEMPLATE.replace('{{PRODUCTION_URL}}', productionUrl);
         writeFileSync(join(cwd, 'PROOF.md'), proof);
-        // Install audit-skill skill to .claude/skills/
+        // Install audit-skill from registry
+        spinner.text = 'Fetching audit-skill...';
         const skillDir = join(cwd, '.claude', 'skills', 'audit-skill');
-        mkdirSync(skillDir, { recursive: true });
-        writeFileSync(join(skillDir, 'SKILL.md'), AUDIT_SKILL_MD);
-        writeFileSync(join(skillDir, 'CRITERIA.md'), AUDIT_CRITERIA_MD);
+        const emitter = degit('skillsets-cc/main/tools/audit-skill', {
+            cache: false,
+            force: true,
+            verbose: false,
+        });
+        await emitter.clone(skillDir);
         spinner.succeed('Skillset structure created');
         // Summary
         console.log(chalk.green('\n✓ Initialized skillset submission:\n'));

package/dist/commands/install.d.ts

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

package/dist/commands/install.js

@@ -1,9 +1,39 @@
 import degit from 'degit';
 import chalk from 'chalk';
 import ora from 'ora';
+import { confirm } from '@inquirer/prompts';
 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';
+function formatMcpWarning(mcpServers, skillsetId) {
+    let output = chalk.yellow('\n⚠  This skillset includes MCP servers:\n');
+    const nativeServers = mcpServers.filter(s => s.type !== 'docker');
+    const dockerServers = mcpServers.filter(s => s.type === 'docker');
+    if (nativeServers.length > 0) {
+        output += chalk.white('\n  Claude Code managed:\n');
+        for (const server of nativeServers) {
+            const detail = server.type === 'stdio'
+                ? `(${server.command} ${(server.args || []).join(' ')})`
+                : `(${server.url})`;
+            output += `    ${server.type}: ${server.name} ${detail}\n`;
+            output += chalk.gray(`      Reputation: ${server.mcp_reputation} (as of ${server.researched_at})\n`);
+        }
+    }
+    if (dockerServers.length > 0) {
+        output += chalk.white('\n  Docker hosted:\n');
+        for (const server of dockerServers) {
+            output += `    image: ${server.image}\n`;
+            output += chalk.gray(`      Reputation: ${server.mcp_reputation} (as of ${server.researched_at})\n`);
+            if (server.servers && server.servers.length > 0) {
+                output += `      Runs: ${server.servers.map(s => s.name).join(', ')}\n`;
+            }
+        }
+    }
+    output += chalk.gray('\n  MCP packages are fetched at runtime and may have changed since audit.\n');
+    output += chalk.cyan(`\n  Review before installing:\n    https://github.com/skillsets-cc/main/tree/main/skillsets/${skillsetId}/content\n`);
+    return output;
+}
 export async function install(skillsetId, options) {
     const spinner = ora(`Installing ${skillsetId}...`).start();
     // Check for conflicts
@@ -22,10 +52,40 @@ export async function install(skillsetId, options) {
         spinner.text = 'Backing up existing files...';
         await backupFiles(conflicts, process.cwd());
     }
+    // Fetch metadata and check for MCP servers BEFORE degit
+    spinner.text = 'Fetching skillset metadata...';
+    try {
+        const metadata = await fetchSkillsetMetadata(skillsetId);
+        if (metadata?.mcp_servers && metadata.mcp_servers.length > 0) {
+            spinner.stop();
+            // Non-interactive check
+            if (!process.stdin.isTTY && !options.acceptMcp) {
+                console.log(chalk.red('This skillset includes MCP servers. Use --accept-mcp to install in non-interactive environments.'));
+                process.exit(1);
+                return;
+            }
+            if (!options.acceptMcp) {
+                console.log(formatMcpWarning(metadata.mcp_servers, skillsetId));
+                const accepted = await confirm({
+                    message: 'Install MCP servers?',
+                    default: false,
+                });
+                if (!accepted) {
+                    console.log(chalk.gray('\nInstallation cancelled.'));
+                    return;
+                }
+            }
+            spinner.start('Downloading skillset...');
+        }
+    }
+    catch {
+        // If metadata fetch fails, continue without MCP check
+        // (registry might be down, don't block install)
+    }
     // Install using degit (extract content/ subdirectory)
     spinner.text = 'Downloading skillset...';
     const emitter = degit(`${REGISTRY_REPO}/skillsets/${skillsetId}/content`, {
-        cache: true,
+        cache: false,
         force: true,
         verbose: false,
     });

package/dist/index.js

@@ -46,6 +46,7 @@ program
     .argument('<skillsetId>', 'Skillset ID (e.g., @user/skillset-name)')
     .option('-f, --force', 'Overwrite existing files')
     .option('-b, --backup', 'Backup existing files before install')
+    .option('--accept-mcp', 'Accept MCP servers without prompting (required for non-interactive environments)')
     .action(async (skillsetId, options) => {
     try {
         await install(skillsetId, options);
@@ -70,9 +71,10 @@ program
 program
     .command('audit')
     .description('Validate skillset and generate audit report')
-    .action(async () => {
+    .option('--check', 'Validate without writing AUDIT_REPORT.md (used by CI)')
+    .action(async (options) => {
     try {
-        await audit();
+        await audit(options);
     }
     catch (error) {
         handleError(error);

package/dist/lib/validate-mcp.d.ts

@@ -0,0 +1,9 @@
+export interface McpValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates MCP server declarations between content files and skillset.yaml.
+ * Bidirectional: content→manifest and manifest→content.
+ */
+export declare function validateMcpServers(skillsetDir: string): McpValidationResult;

package/dist/lib/validate-mcp.js

@@ -0,0 +1,294 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+/**
+ * Validates MCP server declarations between content files and skillset.yaml.
+ * Bidirectional: content→manifest and manifest→content.
+ */
+export function validateMcpServers(skillsetDir) {
+    const errors = [];
+    // 1. Collect from content
+    const contentServers = collectContentServers(skillsetDir, errors);
+    // 2. Collect from manifest
+    const manifestServers = collectManifestServers(skillsetDir, errors);
+    // If we hit parse errors, return early
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    // 3. No MCPs anywhere = pass
+    if (contentServers.length === 0 && manifestServers.length === 0) {
+        return { valid: true, errors: [] };
+    }
+    // 4. Content→manifest check
+    for (const cs of contentServers) {
+        const match = findManifestMatch(cs, manifestServers);
+        if (!match) {
+            errors.push(`MCP server '${cs.name}' found in content but not declared in skillset.yaml mcp_servers`);
+        }
+    }
+    // 5. Manifest→content check
+    for (const ms of manifestServers) {
+        if (ms.type === 'docker') {
+            // Check Docker inner servers
+            for (const inner of ms.servers || []) {
+                const match = contentServers.find(cs => cs.source === 'docker' && cs.name === inner.name);
+                if (!match) {
+                    errors.push(`Docker inner server '${inner.name}' declared in manifest but not found in content docker config`);
+                }
+            }
+            // Check Docker image exists in compose
+            validateDockerImage(skillsetDir, ms.image, errors);
+        }
+        else {
+            const match = contentServers.find(cs => cs.source === 'native' && cs.name === ms.name);
+            if (!match) {
+                errors.push(`MCP server '${ms.name}' declared in skillset.yaml but not found in content`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * 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;
+    }
+    // 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)) {
+                    servers.push({
+                        name,
+                        source: 'native',
+                        command: config.command,
+                        args: config.args,
+                        url: config.url,
+                    });
+                }
+            }
+        }
+        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}`);
+        }
+    }
+    // 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}`);
+        }
+    }
+    // 4. Check docker/**/*.yaml and docker/**/*.yml for mcp_servers key
+    const dockerDir = join(contentDir, 'docker');
+    if (existsSync(dockerDir)) {
+        const yamlFiles = findYamlFiles(dockerDir);
+        for (const yamlPath of yamlFiles) {
+            try {
+                const content = readFileSync(yamlPath, 'utf-8');
+                const data = yaml.load(content);
+                if (data.mcp_servers && typeof data.mcp_servers === 'object') {
+                    for (const [name, config] of Object.entries(data.mcp_servers)) {
+                        // Avoid duplicates across multiple yaml files
+                        if (!servers.some(s => s.name === name && s.source === 'docker')) {
+                            servers.push({
+                                name,
+                                source: 'docker',
+                                command: config.command,
+                                args: config.args,
+                            });
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                errors.push(`Failed to parse ${yamlPath}: ${error.message}`);
+            }
+        }
+    }
+    return servers;
+}
+/**
+ * Collect MCP servers from skillset.yaml manifest
+ */
+function collectManifestServers(skillsetDir, errors) {
+    const manifestPath = join(skillsetDir, 'skillset.yaml');
+    if (!existsSync(manifestPath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(manifestPath, 'utf-8');
+        const data = yaml.load(content);
+        if (!data.mcp_servers || !Array.isArray(data.mcp_servers)) {
+            return [];
+        }
+        return data.mcp_servers;
+    }
+    catch (error) {
+        errors.push(`Failed to parse skillset.yaml: ${error.message}`);
+        return [];
+    }
+}
+/**
+ * Find a matching manifest entry for a content server
+ */
+function findManifestMatch(contentServer, manifestServers) {
+    for (const ms of manifestServers) {
+        if (contentServer.source === 'native') {
+            // Native server: match by name and verify command/url
+            if (ms.name !== contentServer.name || ms.type === 'docker') {
+                continue;
+            }
+            // For stdio type, check command and args
+            if (ms.type === 'stdio') {
+                if (ms.command === contentServer.command) {
+                    // Check args match (both undefined or same array)
+                    const msArgs = ms.args || [];
+                    const csArgs = contentServer.args || [];
+                    if (arraysEqual(msArgs, csArgs)) {
+                        return ms;
+                    }
+                }
+            }
+            // For http type, check url
+            if (ms.type === 'http' && ms.url === contentServer.url) {
+                return ms;
+            }
+        }
+        else if (contentServer.source === 'docker') {
+            // Docker server: match within servers array
+            if (ms.type === 'docker' && ms.servers) {
+                for (const inner of ms.servers) {
+                    if (inner.name === contentServer.name) {
+                        // Check command and args match
+                        if (inner.command === contentServer.command) {
+                            const innerArgs = inner.args || [];
+                            const csArgs = contentServer.args || [];
+                            if (arraysEqual(innerArgs, csArgs)) {
+                                return ms;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate that a Docker image exists in any YAML file under docker/ (compose or otherwise)
+ */
+function validateDockerImage(skillsetDir, image, errors) {
+    const contentDir = join(skillsetDir, 'content');
+    const dockerDir = join(contentDir, 'docker');
+    if (!existsSync(dockerDir)) {
+        errors.push(`Docker image '${image}' declared but no docker directory found`);
+        return;
+    }
+    const yamlFiles = findYamlFiles(dockerDir);
+    let found = false;
+    for (const yamlPath of yamlFiles) {
+        try {
+            const content = readFileSync(yamlPath, 'utf-8');
+            const data = yaml.load(content);
+            // Check if any service uses the specified image
+            if (data.services && typeof data.services === 'object') {
+                for (const service of Object.values(data.services)) {
+                    if (service.image === image) {
+                        found = true;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            // Parse errors for compose files are non-fatal here — already caught in content scanning
+        }
+        if (found)
+            break;
+    }
+    if (!found) {
+        errors.push(`Docker image '${image}' not found in any YAML file under docker/`);
+    }
+}
+/**
+ * Recursively find all YAML files (.yaml, .yml) in a directory
+ */
+function findYamlFiles(dir) {
+    const results = [];
+    if (!existsSync(dir)) {
+        return results;
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...findYamlFiles(fullPath));
+        }
+        else if (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml')) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Compare two arrays for equality
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}

package/dist/types/index.d.ts

@@ -31,6 +31,7 @@ export interface SearchIndexEntry {
     entry_point: string;
     checksum: string;
     files: Record<string, string>;
+    mcp_servers?: McpServer[];
 }
 export interface StatsResponse {
     stars: Record<string, number>;
@@ -60,4 +61,23 @@ export interface Skillset {
     };
     status: 'active' | 'deprecated' | 'archived';
     entry_point: string;
+    mcp_servers?: McpServer[];
+}
+export interface McpServerInner {
+    name: string;
+    command: string;
+    args?: string[];
+    mcp_reputation: string;
+    researched_at: string;
+}
+export interface McpServer {
+    name: string;
+    type: 'stdio' | 'http' | 'docker';
+    command?: string;
+    args?: string[];
+    url?: string;
+    image?: string;
+    servers?: McpServerInner[];
+    mcp_reputation: string;
+    researched_at: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsets",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "CLI tool for discovering and installing verified skillsets",
   "type": "module",
   "bin": {