agent-skills-cli 1.1.2 → 1.1.4

package/dist/core/skill-tester.js

@@ -0,0 +1,201 @@
+/**
+ * Skill Testing Framework
+ * Run static and dynamic assertions against skills.
+ *
+ * Test definitions can come from:
+ *   1. skill-test.yml in the skill directory
+ *   2. tests section in SKILL.md frontmatter
+ *   3. Built-in structural checks
+ */
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, basename } from 'path';
+import matter from 'gray-matter';
+// ── Built-in Tests ───────────────────────────────────────────────────────
+function getBuiltinTests() {
+    return [
+        {
+            name: 'Has frontmatter name',
+            type: 'structure',
+            assertion: 'SKILL.md must have a name field in frontmatter',
+            check: (_content, data) => !!data.name && typeof data.name === 'string',
+        },
+        {
+            name: 'Has frontmatter description',
+            type: 'structure',
+            assertion: 'SKILL.md must have a description field in frontmatter',
+            check: (_content, data) => !!data.description && typeof data.description === 'string' && data.description.length > 10,
+        },
+        {
+            name: 'Has meaningful content',
+            type: 'content',
+            assertion: 'SKILL.md body should have at least 50 characters',
+            check: (content) => content.trim().length >= 50,
+        },
+        {
+            name: 'Has section headings',
+            type: 'structure',
+            assertion: 'SKILL.md should have at least one ## heading',
+            check: (content) => /^#{2,4}\s+.+/m.test(content),
+        },
+        {
+            name: 'Has "when to use" section',
+            type: 'content',
+            assertion: 'Should describe when the skill should be used',
+            check: (content) => /when\s+to\s+use|usage|use\s+cases?|scenarios?/i.test(content),
+        },
+        {
+            name: 'Has actionable instructions',
+            type: 'content',
+            assertion: 'Should contain numbered steps or bullet points',
+            check: (content) => /^\s*[-*]\s+.+/m.test(content) || /^\s*\d+\.\s+.+/m.test(content),
+        },
+        {
+            name: 'Has code examples',
+            type: 'content',
+            assertion: 'Should include at least one code block',
+            check: (content) => /```[\s\S]*?```/.test(content),
+        },
+        {
+            name: 'Description is concise',
+            type: 'quality',
+            assertion: 'Description should be under 200 characters',
+            check: (_content, data) => !data.description || data.description.length <= 200,
+        },
+        {
+            name: 'No placeholder content',
+            type: 'quality',
+            assertion: 'Should not contain TODO, FIXME, or placeholder text',
+            check: (content) => !/\b(TODO|FIXME|PLACEHOLDER|CHANGE\s+ME|INSERT\s+HERE)\b/i.test(content),
+        },
+        {
+            name: 'Reasonable length',
+            type: 'quality',
+            assertion: 'SKILL.md should be between 100 and 50,000 characters',
+            check: (content) => content.length >= 100 && content.length <= 50000,
+        },
+    ];
+}
+// ── Custom Test Parsing ──────────────────────────────────────────────────
+/**
+ * Load custom tests from skill-test.yml if it exists.
+ */
+async function loadCustomTests(skillDir) {
+    const testFile = join(skillDir, 'skill-test.yml');
+    if (!existsSync(testFile))
+        return [];
+    try {
+        const raw = await readFile(testFile, 'utf-8');
+        const { data } = matter(`---\n${raw}\n---`);
+        if (!data.tests || !Array.isArray(data.tests))
+            return [];
+        return data.tests.map((t) => ({
+            name: t.name || 'Custom test',
+            type: 'content',
+            assertion: t.assertion || t.name,
+            check: (content) => {
+                let pass = true;
+                if (t.expect_contains) {
+                    for (const kw of t.expect_contains) {
+                        if (!content.includes(kw))
+                            pass = false;
+                    }
+                }
+                if (t.expect_not_contains) {
+                    for (const kw of t.expect_not_contains) {
+                        if (content.includes(kw))
+                            pass = false;
+                    }
+                }
+                if (t.expect_min_length) {
+                    if (content.length < t.expect_min_length)
+                        pass = false;
+                }
+                if (t.expect_sections) {
+                    for (const section of t.expect_sections) {
+                        if (!new RegExp(`^#{2,4}\\s+${section}`, 'im').test(content))
+                            pass = false;
+                    }
+                }
+                return pass;
+            },
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ── Main Entry ───────────────────────────────────────────────────────────
+/**
+ * Run all tests against a skill.
+ *
+ * @param skillPath — path to skill directory or SKILL.md
+ */
+export async function testSkill(skillPath) {
+    const start = Date.now();
+    const skillMd = skillPath.endsWith('SKILL.md') ? skillPath : join(skillPath, 'SKILL.md');
+    const skillDir = skillPath.endsWith('SKILL.md') ? join(skillPath, '..') : skillPath;
+    if (!existsSync(skillMd)) {
+        throw new Error(`SKILL.md not found at ${skillMd}`);
+    }
+    const raw = await readFile(skillMd, 'utf-8');
+    const { data, content } = matter(raw);
+    const name = data.name || basename(skillDir);
+    // Combine built-in + custom tests
+    const builtinTests = getBuiltinTests();
+    const customTests = await loadCustomTests(skillDir);
+    const allTests = [...builtinTests, ...customTests];
+    // Run tests
+    const assertions = [];
+    for (const test of allTests) {
+        try {
+            const passed = test.check(content, data);
+            assertions.push({
+                name: test.name,
+                passed,
+                type: test.type,
+                message: passed ? undefined : test.assertion,
+            });
+        }
+        catch (err) {
+            assertions.push({
+                name: test.name,
+                passed: false,
+                type: test.type,
+                message: `Error: ${err.message || err}`,
+            });
+        }
+    }
+    const passedCount = assertions.filter(a => a.passed).length;
+    return {
+        skillName: name,
+        skillPath: skillDir,
+        assertions,
+        passed: assertions.every(a => a.passed),
+        duration: Date.now() - start,
+        passRate: Math.round((passedCount / assertions.length) * 100),
+    };
+}
+/**
+ * Run tests against multiple skills.
+ */
+export async function testSkills(skillPaths) {
+    const results = [];
+    for (const path of skillPaths) {
+        try {
+            results.push(await testSkill(path));
+        }
+        catch (err) {
+            results.push({
+                skillName: basename(path),
+                skillPath: path,
+                assertions: [{ name: 'Load skill', passed: false, type: 'structure', message: err.message }],
+                passed: false,
+                duration: 0,
+                passRate: 0,
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=skill-tester.js.map

package/dist/core/skill-tester.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-tester.js","sourceRoot":"","sources":["../../src/core/skill-tester.ts"],"names":[],"mappings":"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"}

package/dist/core/splitter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Skill Splitter Module
+ * Splits a monolithic skill into focused sub-skills based on topic sections.
+ */
+export interface SplitSkill {
+    /** Suggested name for this sub-skill */
+    name: string;
+    /** Section heading(s) this came from */
+    headings: string[];
+    /** Content body */
+    body: string;
+    /** Full SKILL.md content with frontmatter */
+    fullContent: string;
+    /** Estimated token count */
+    tokens: number;
+}
+export interface SplitResult {
+    /** Original skill name */
+    originalName: string;
+    /** Original token count */
+    originalTokens: number;
+    /** Generated sub-skills */
+    skills: SplitSkill[];
+    /** Whether the split was meaningful */
+    worthSplitting: boolean;
+    /** Reason if not worth it */
+    reason?: string;
+}
+/**
+ * Split a skill into sub-skills based on topic clustering.
+ *
+ * @param skillPath — path to skill directory or SKILL.md
+ * @param minSections — minimum sections per sub-skill (default 2)
+ */
+export declare function splitSkill(skillPath: string, minSections?: number): Promise<SplitResult>;
+//# sourceMappingURL=splitter.d.ts.map

package/dist/core/splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.d.ts","sourceRoot":"","sources":["../../src/core/splitter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IACxB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,uCAAuC;IACvC,cAAc,EAAE,OAAO,CAAC;IACxB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;;;GAKG;AACH,wBAAsB,UAAU,CAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAU,GACxB,OAAO,CAAC,WAAW,CAAC,CAmEtB"}

package/dist/core/splitter.js

@@ -0,0 +1,186 @@
+/**
+ * Skill Splitter Module
+ * Splits a monolithic skill into focused sub-skills based on topic sections.
+ */
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, basename } from 'path';
+import matter from 'gray-matter';
+// ── Main Entry ───────────────────────────────────────────────────────────
+/**
+ * Split a skill into sub-skills based on topic clustering.
+ *
+ * @param skillPath — path to skill directory or SKILL.md
+ * @param minSections — minimum sections per sub-skill (default 2)
+ */
+export async function splitSkill(skillPath, minSections = 2) {
+    const skillMd = skillPath.endsWith('SKILL.md') ? skillPath : join(skillPath, 'SKILL.md');
+    if (!existsSync(skillMd))
+        throw new Error(`SKILL.md not found at ${skillMd}`);
+    const raw = await readFile(skillMd, 'utf-8');
+    const { data, content } = matter(raw);
+    const name = data.name || basename(skillPath);
+    const originalTokens = Math.ceil(raw.length / 4);
+    // Parse into sections
+    const sections = parseSections(content);
+    // Not worth splitting if too few sections
+    if (sections.length < 3) {
+        return {
+            originalName: name,
+            originalTokens,
+            skills: [],
+            worthSplitting: false,
+            reason: `Only ${sections.length} section(s) found — too few to split meaningfully.`,
+        };
+    }
+    // Group sections by topic similarity
+    const groups = clusterSections(sections, minSections);
+    if (groups.length <= 1) {
+        return {
+            originalName: name,
+            originalTokens,
+            skills: [],
+            worthSplitting: false,
+            reason: 'All sections belong to a single coherent topic.',
+        };
+    }
+    // Build sub-skills
+    const subSkills = groups.map((group, i) => {
+        const subName = group.suggestedName || `${name}-part-${i + 1}`;
+        const headings = group.sections.map(s => s.heading);
+        const body = group.sections.map(s => `## ${s.heading}\n${s.content}`).join('\n\n');
+        const fullContent = [
+            '---',
+            `name: ${subName}`,
+            `description: "Split from ${name}: ${headings.slice(0, 2).join(', ')}"`,
+            `split_from: "${name}"`,
+            '---',
+            '',
+            body,
+        ].join('\n');
+        return {
+            name: subName,
+            headings,
+            body,
+            fullContent,
+            tokens: Math.ceil(fullContent.length / 4),
+        };
+    });
+    return {
+        originalName: name,
+        originalTokens,
+        skills: subSkills,
+        worthSplitting: true,
+    };
+}
+function parseSections(body) {
+    const lines = body.split('\n');
+    const sections = [];
+    let currentHeading = '';
+    let currentLevel = 0;
+    let currentLines = [];
+    for (const line of lines) {
+        const match = line.match(/^(#{2,4})\s+(.+)/);
+        if (match) {
+            if (currentHeading && currentLines.length > 0) {
+                const content = currentLines.join('\n');
+                sections.push({
+                    heading: currentHeading,
+                    level: currentLevel,
+                    content,
+                    keywords: extractKeywords(currentHeading + ' ' + content),
+                });
+            }
+            currentHeading = match[2].trim();
+            currentLevel = match[1].length;
+            currentLines = [];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    if (currentHeading && currentLines.length > 0) {
+        const content = currentLines.join('\n');
+        sections.push({
+            heading: currentHeading,
+            level: currentLevel,
+            content,
+            keywords: extractKeywords(currentHeading + ' ' + content),
+        });
+    }
+    return sections;
+}
+function clusterSections(sections, minPerGroup) {
+    // Topic categories for clustering
+    const topicGroups = {
+        'setup': ['install', 'setup', 'getting started', 'prerequisites', 'requirements', 'configuration', 'config'],
+        'coding-style': ['style', 'format', 'naming', 'conventions', 'lint', 'prettier', 'eslint', 'pattern'],
+        'testing': ['test', 'spec', 'jest', 'vitest', 'mocha', 'assert', 'coverage', 'mock'],
+        'architecture': ['architecture', 'structure', 'pattern', 'component', 'module', 'design', 'layer'],
+        'deployment': ['deploy', 'build', 'ci', 'cd', 'docker', 'kubernetes', 'production', 'hosting'],
+        'security': ['security', 'auth', 'token', 'password', 'encrypt', 'cors', 'xss', 'vulnerability'],
+        'api': ['api', 'rest', 'graphql', 'endpoint', 'route', 'middleware', 'handler'],
+        'database': ['database', 'sql', 'query', 'model', 'schema', 'migration', 'orm', 'prisma'],
+        'documentation': ['doc', 'readme', 'changelog', 'comment', 'jsdoc', 'tsdoc'],
+        'performance': ['performance', 'optimize', 'cache', 'lazy', 'bundle', 'minify', 'compress'],
+    };
+    // Assign each section to a topic
+    const assigned = new Map();
+    for (const section of sections) {
+        let bestTopic = 'other';
+        let bestScore = 0;
+        for (const [topic, keywords] of Object.entries(topicGroups)) {
+            const score = section.keywords.filter(kw => keywords.some(tk => kw.includes(tk) || tk.includes(kw))).length;
+            if (score > bestScore) {
+                bestScore = score;
+                bestTopic = topic;
+            }
+        }
+        if (!assigned.has(bestTopic))
+            assigned.set(bestTopic, []);
+        assigned.get(bestTopic).push(section);
+    }
+    // Filter groups that have enough sections
+    const groups = [];
+    const overflow = [];
+    for (const [topic, secs] of assigned) {
+        if (secs.length >= minPerGroup) {
+            groups.push({ sections: secs, suggestedName: topic });
+        }
+        else {
+            overflow.push(...secs);
+        }
+    }
+    // Add overflow sections to the closest group or create an "other" group
+    if (overflow.length > 0) {
+        if (overflow.length >= minPerGroup) {
+            groups.push({ sections: overflow, suggestedName: 'general' });
+        }
+        else if (groups.length > 0) {
+            // Add to the largest group
+            groups.sort((a, b) => b.sections.length - a.sections.length);
+            groups[0].sections.push(...overflow);
+        }
+        else {
+            // All sections are in overflow — not worth splitting
+            return [{ sections: overflow, suggestedName: 'general' }];
+        }
+    }
+    return groups;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should',
+    'could', 'may', 'might', 'shall', 'can', 'need', 'must',
+    'use', 'using', 'used', 'make', 'sure', 'file', 'code',
+]);
+function extractKeywords(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length >= 3 && !STOP_WORDS.has(w));
+}
+//# sourceMappingURL=splitter.js.map

package/dist/core/splitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.js","sourceRoot":"","sources":["../../src/core/splitter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skills-cli",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Universal CLI for Agent Skills - works with 42 AI agents including Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Zed, and more. Supports private Git repos, npm packages, and enterprise configurations.",
   "type": "module",
   "main": "dist/index.js",