@gulibs/safe-coder 0.0.23 → 0.0.25

package/dist/documentation/skill-generator.d.ts

@@ -1,4 +1,4 @@
-import type { CrawlResult } from './doc-crawler.js';
+import type { CrawledPage, CrawlResult } from './doc-crawler.js';
 export interface SkillMetadata {
     title: string;
     description: string;
@@ -22,6 +22,8 @@ export interface SavedSkillFiles {
 export declare class SkillGenerator {
     private readonly CONTENT_PREVIEW_LENGTH;
     private readonly MIN_CATEGORIZATION_SCORE;
+    private readonly MIN_CONTENT_LENGTH;
+    private readonly MIN_HEADINGS_COUNT;
     /**
      * Generate agent skill from crawled documentation
      */
@@ -35,9 +37,26 @@ export declare class SkillGenerator {
      */
     private extractTitle;
     /**
-     * Generate description
+     * Generate description with "when to use" triggers and keywords extracted from pages
+     * Description must be comprehensive, include triggers, and stay within 1024 chars
      */
     private generateDescription;
+    /**
+     * Extract key topics from page titles, headings, and content
+     */
+    private extractKeyTopics;
+    /**
+     * Extract domain name from URL
+     */
+    private extractDomainName;
+    /**
+     * Extract use cases from pages and categories
+     */
+    private extractUseCases;
+    /**
+     * Generate trigger keywords from categories and topics
+     */
+    private generateTriggers;
     /**
      * Categorize pages into categories based on URL patterns and content
      */
@@ -49,12 +68,18 @@ export declare class SkillGenerator {
     /**
      * Generate reference files for each category
      * Includes full content, code examples, and table of contents from headings
+     * Adds table of contents at the top for files longer than 100 lines
      */
     private generateReferenceFiles;
     /**
      * Generate SKILL.md with YAML frontmatter
+     * Optimized for progressive disclosure - concise body focused on procedural instructions
      */
     private generateSkillMd;
+    /**
+     * Get guidance on when to read a specific category reference file
+     */
+    private getWhenToReadGuidance;
     /**
      * Save skill to file system in proper directory structure
      * Prevents nested skill directories by checking if outputDir is already a skill directory
@@ -68,5 +93,16 @@ export declare class SkillGenerator {
      * Capitalize first letter
      */
     private capitalize;
+    /**
+     * Check if crawled content is sufficient for skill generation
+     */
+    canGenerateSkill(pages: CrawledPage[]): {
+        canGenerate: boolean;
+        reason?: string;
+    };
+    /**
+     * Validate description quality - checks length and presence of trigger keywords
+     */
+    private validateDescription;
 }
 //# sourceMappingURL=skill-generator.d.ts.map

package/dist/documentation/skill-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-generator.d.ts","sourceRoot":"","sources":["../../src/documentation/skill-generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAO;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAE9C;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc;IA6C5F;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA4BzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAiBpB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAsDvB;;OAEG;IACH,OAAO,CAAC,eAAe;IA0CvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAsD9B;;OAEG;IACH,OAAO,CAAC,eAAe;IAoEvB;;;OAGG;IACG,SAAS,CACX,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;IA4D3B;;OAEG;IACH,OAAO,CAAC,OAAO;IASf;;OAEG;IACH,OAAO,CAAC,UAAU;CAGrB"}
+{"version":3,"file":"skill-generator.d.ts","sourceRoot":"","sources":["../../src/documentation/skill-generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAO;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAC9C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAK;IAExC;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc;IA0D5F;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA4BzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAmD3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;IACH,OAAO,CAAC,eAAe;IA6BvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAsDvB;;OAEG;IACH,OAAO,CAAC,eAAe;IA0CvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IA2F9B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAyDvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;;OAGG;IACG,SAAS,CACX,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;IAyE3B;;OAEG;IACH,OAAO,CAAC,OAAO;IASf;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAoDjF;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAoB9B"}

package/dist/documentation/skill-generator.js

@@ -1,8 +1,10 @@
 import { writeFile, mkdir, access, constants } from 'fs/promises';
-import { join, resolve } from 'path';
+import { join, resolve, basename } from 'path';
 export class SkillGenerator {
     CONTENT_PREVIEW_LENGTH = 500;
     MIN_CATEGORIZATION_SCORE = 2;
+    MIN_CONTENT_LENGTH = 100; // Minimum characters for valid content
+    MIN_HEADINGS_COUNT = 1; // Minimum headings for structured content
     /**
      * Generate agent skill from crawled documentation
      */
@@ -11,13 +13,22 @@ export class SkillGenerator {
         if (pages.length === 0) {
             throw new Error('No pages were successfully crawled');
         }
+        // Validate if content is sufficient for skill generation
+        const validation = this.canGenerateSkill(pages);
+        if (!validation.canGenerate) {
+            throw new Error(`Cannot generate skill: ${validation.reason}. ` +
+                `Pages crawled: ${totalPages}, but content is insufficient. ` +
+                `Consider crawling more pages or a different website.`);
+        }
         // Generate skill name
         const name = skillName || this.generateSkillName(rootUrl, pages[0]);
         // Generate title from root URL or first page
         const title = this.extractTitle(rootUrl, pages[0]);
         // Generate description (truncated to 1024 chars)
-        const description = this.generateDescription(rootUrl, totalPages, maxDepthReached);
+        const description = this.generateDescription(rootUrl, pages, totalPages, maxDepthReached);
         const truncatedDescription = description.length > 1024 ? description.substring(0, 1021) + '...' : description;
+        // Validate description quality
+        this.validateDescription(truncatedDescription);
         // Categorize pages
         const categories = this.categorizePages(pages);
         // Generate reference files
@@ -89,10 +100,139 @@ export class SkillGenerator {
         }
     }
     /**
-     * Generate description
+     * Generate description with "when to use" triggers and keywords extracted from pages
+     * Description must be comprehensive, include triggers, and stay within 1024 chars
      */
-    generateDescription(rootUrl, totalPages, maxDepth) {
-        return `Use when working with documentation at ${rootUrl}. Comprehensive documentation skill generated from ${rootUrl}. Crawled ${totalPages} pages up to depth ${maxDepth}.`;
+    generateDescription(rootUrl, pages, totalPages, maxDepth) {
+        // Extract key topics and concepts from pages
+        const topics = this.extractKeyTopics(pages);
+        const categories = this.inferCategories(pages);
+        const categoryNames = Array.from(categories.keys());
+        // Build description components
+        const parts = [];
+        // What the skill provides
+        const domainName = this.extractDomainName(rootUrl);
+        parts.push(`Comprehensive documentation for ${domainName}`);
+        // Extract use cases from page titles and categories
+        const useCases = this.extractUseCases(pages, categoryNames);
+        if (useCases.length > 0) {
+            // Format use cases more naturally
+            const useCaseText = useCases.length === 1
+                ? useCases[0]
+                : useCases.slice(0, -1).join(', ') + (useCases.length > 1 ? `, and ${useCases[useCases.length - 1]}` : '');
+            parts.push(`Use when working with ${domainName} ${useCaseText}`);
+        }
+        // Add specific triggers/keywords based on categories and topics
+        const triggers = this.generateTriggers(categoryNames, topics);
+        if (triggers.length > 0) {
+            // Include triggers naturally in the description
+            const triggerText = triggers.slice(0, 5).join(', ');
+            parts.push(`Includes documentation for ${triggerText}`);
+        }
+        // Add metadata (crawled info) - keep it brief
+        parts.push(`Generated from ${rootUrl} (${totalPages} pages, depth ${maxDepth})`);
+        // Join and truncate to 1024 chars, preserving key information
+        let description = parts.join('. ');
+        if (description.length > 1024) {
+            // Prioritize: what it does + use cases + triggers, then metadata
+            const essential = `${parts[0]}. ${parts[1] || ''}${parts[2] ? `. ${parts[2]}` : ''}`;
+            const metadata = parts[3] || '';
+            const available = 1024 - essential.length - metadata.length - 10; // 10 for spacing/ellipsis
+            if (available > 0 && metadata.length > available) {
+                description = `${essential}. ${metadata.substring(0, available)}...`;
+            }
+            else {
+                description = `${essential}. ${metadata}`.substring(0, 1021) + '...';
+            }
+        }
+        return description;
+    }
+    /**
+     * Extract key topics from page titles, headings, and content
+     */
+    extractKeyTopics(pages) {
+        const topicSet = new Set();
+        const commonWords = new Set(['the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'from', 'as', 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should', 'could', 'may', 'might', 'must', 'can', 'this', 'that', 'these', 'those', 'what', 'which', 'who', 'when', 'where', 'why', 'how', 'get', 'got', 'go', 'goes', 'went', 'come', 'comes', 'came', 'see', 'saw', 'know', 'knows', 'knew', 'think', 'thinks', 'thought', 'take', 'takes', 'took', 'make', 'makes', 'made', 'use', 'uses', 'used', 'work', 'works', 'worked', 'call', 'calls', 'called']);
+        // Extract from titles
+        for (const page of pages.slice(0, 20)) { // Limit to first 20 pages for performance
+            const titleWords = (page.title || '').toLowerCase().split(/\s+/)
+                .filter(w => w.length > 3 && !commonWords.has(w))
+                .slice(0, 5);
+            titleWords.forEach(w => topicSet.add(w));
+        }
+        // Extract from headings
+        for (const page of pages.slice(0, 20)) {
+            if (page.headings) {
+                for (const heading of page.headings.slice(0, 10)) {
+                    const headingWords = (heading.text || '').toLowerCase().split(/\s+/)
+                        .filter(w => w.length > 3 && !commonWords.has(w))
+                        .slice(0, 3);
+                    headingWords.forEach(w => topicSet.add(w));
+                }
+            }
+        }
+        return Array.from(topicSet).slice(0, 10); // Limit to top 10 topics
+    }
+    /**
+     * Extract domain name from URL
+     */
+    extractDomainName(rootUrl) {
+        try {
+            const url = new URL(rootUrl);
+            const hostname = url.hostname.replace('www.', '');
+            const pathParts = url.pathname.split('/').filter(p => p && !['docs', 'documentation', 'en', 'stable', 'latest'].includes(p));
+            if (pathParts.length > 0) {
+                return `${hostname} ${pathParts[pathParts.length - 1]}`;
+            }
+            return hostname;
+        }
+        catch {
+            return 'documentation';
+        }
+    }
+    /**
+     * Extract use cases from pages and categories
+     */
+    extractUseCases(pages, categoryNames) {
+        const useCases = [];
+        // Map categories to use cases
+        const categoryToUseCase = {
+            'api': 'for API reference and methods',
+            'tutorials': 'for tutorials and learning',
+            'tutorial': 'for tutorials and learning',
+            'guide': 'for guides and how-tos',
+            'getting-started': 'for getting started',
+            'reference': 'for reference documentation',
+            'examples': 'for code examples',
+        };
+        for (const cat of categoryNames) {
+            const useCase = categoryToUseCase[cat.toLowerCase()];
+            if (useCase && !useCases.includes(useCase)) {
+                useCases.push(useCase);
+            }
+        }
+        // If no specific use cases found, add generic ones
+        if (useCases.length === 0) {
+            useCases.push('for understanding concepts', 'for implementing features', 'for debugging code');
+        }
+        return useCases.slice(0, 3); // Limit to 3 use cases
+    }
+    /**
+     * Generate trigger keywords from categories and topics
+     */
+    generateTriggers(categoryNames, topics) {
+        const triggers = [];
+        // Add category-based triggers
+        for (const cat of categoryNames.slice(0, 3)) {
+            triggers.push(cat);
+        }
+        // Add top topics as triggers
+        for (const topic of topics.slice(0, 3)) {
+            if (!triggers.includes(topic)) {
+                triggers.push(topic);
+            }
+        }
+        return triggers.slice(0, 5); // Limit to 5 triggers
     }
     /**
      * Categorize pages into categories based on URL patterns and content
@@ -187,6 +327,7 @@ export class SkillGenerator {
     /**
      * Generate reference files for each category
      * Includes full content, code examples, and table of contents from headings
+     * Adds table of contents at the top for files longer than 100 lines
      */
     generateReferenceFiles(categories, skillName) {
         const referenceFiles = new Map();
@@ -197,10 +338,23 @@ export class SkillGenerator {
             lines.push(`# ${this.capitalize(skillName)} - ${category.replace('_', ' ').split('-').map(this.capitalize).join(' ')}\n`);
             lines.push(`**Pages:** ${pages.length}\n`);
             lines.push('---\n');
+            // Collect all page titles and headings for table of contents
+            const tocItems = [];
+            for (const page of pages) {
+                const headings = [];
+                if (page.headings && page.headings.length > 0) {
+                    for (const heading of page.headings) {
+                        const level = parseInt(heading.level.replace('h', ''));
+                        headings.push({ level, text: heading.text });
+                    }
+                }
+                tocItems.push({ title: page.title, url: page.url, headings });
+            }
+            // Generate content
             for (const page of pages) {
                 lines.push(`## ${page.title}\n`);
                 lines.push(`**URL:** ${page.url}\n`);
-                // Table of contents from headings
+                // Table of contents from headings (per page)
                 if (page.headings && page.headings.length > 0) {
                     lines.push('**Contents:**');
                     for (const heading of page.headings.slice(0, 10)) {
@@ -229,12 +383,35 @@ export class SkillGenerator {
                 }
                 lines.push('---\n');
             }
-            referenceFiles.set(category, lines.join('\n'));
+            const content = lines.join('\n');
+            const lineCount = content.split('\n').length;
+            // Add table of contents at the top for files longer than 100 lines
+            if (lineCount > 100 && tocItems.length > 0) {
+                const tocLines = [];
+                tocLines.push('## Table of Contents\n');
+                for (const item of tocItems) {
+                    tocLines.push(`- [${item.title}](#${this.slugify(item.title)})`);
+                    // Add sub-headings for major sections
+                    for (const heading of item.headings.slice(0, 3)) {
+                        if (heading.level <= 3) {
+                            const indent = '  '.repeat(heading.level - 2);
+                            tocLines.push(`${indent}- [${heading.text}](#${this.slugify(heading.text)})`);
+                        }
+                    }
+                }
+                tocLines.push('');
+                tocLines.push('---\n');
+                referenceFiles.set(category, tocLines.join('\n') + content);
+            }
+            else {
+                referenceFiles.set(category, content);
+            }
         }
         return referenceFiles;
     }
     /**
      * Generate SKILL.md with YAML frontmatter
+     * Optimized for progressive disclosure - concise body focused on procedural instructions
      */
     generateSkillMd(skillName, description, categories, allPages) {
         const lines = [];
@@ -246,61 +423,91 @@ export class SkillGenerator {
         lines.push('');
         // Title
         lines.push(`# ${this.capitalize(skillName)} Skill\n`);
-        lines.push(`${description}\n`);
-        // When to Use This Skill
-        lines.push('## When to Use This Skill\n');
-        lines.push(`This skill should be triggered when:`);
-        lines.push(`- Working with ${skillName}`);
-        lines.push(`- Asking about ${skillName} features or APIs`);
-        lines.push(`- Implementing ${skillName} solutions`);
-        lines.push(`- Debugging ${skillName} code`);
-        lines.push(`- Learning ${skillName} best practices\n`);
-        // Quick Reference
-        lines.push('## Quick Reference\n');
-        lines.push('*Quick reference patterns will be added as you use the skill.*\n');
-        // Reference Files
+        // Quick Start / Overview
+        lines.push('## Overview\n');
+        lines.push('This skill provides comprehensive documentation extracted from official sources. Use the reference files below to access detailed information as needed.\n');
+        // Reference Files with clear guidance on when to read them
         lines.push('## Reference Files\n');
-        lines.push('This skill includes comprehensive documentation in `references/`:\n');
-        for (const category of Array.from(categories.keys()).sort()) {
+        lines.push('The following reference files contain organized documentation. Read them when you need specific information:\n');
+        const sortedCategories = Array.from(categories.keys()).sort();
+        for (const category of sortedCategories) {
             const pages = categories.get(category) || [];
-            lines.push(`- **${category}.md** - ${category.replace('_', ' ').split('-').map(this.capitalize).join(' ')} documentation (${pages.length} pages)`);
+            const categoryDisplay = category.replace('_', ' ').split('-').map(this.capitalize).join(' ');
+            const whenToRead = this.getWhenToReadGuidance(category);
+            lines.push(`- **[${category}.md](references/${category}.md)** - ${categoryDisplay} documentation (${pages.length} pages)`);
+            if (whenToRead) {
+                lines.push(`  - *Read when: ${whenToRead}*`);
+            }
         }
         lines.push('');
-        // Working with This Skill
+        // Working with This Skill (procedural guidance)
         lines.push('## Working with This Skill\n');
-        lines.push('### For Beginners');
-        lines.push('Start with the getting_started or tutorials reference files for foundational concepts.\n');
-        lines.push('### For Specific Features');
-        lines.push('Use the appropriate category reference file (api, guides, etc.) for detailed information.\n');
-        lines.push('### For Code Examples');
-        lines.push('The quick reference section above contains common patterns extracted from the official docs.\n');
-        // Resources
-        lines.push('## Resources\n');
-        lines.push('### references/');
-        lines.push('Organized documentation extracted from official sources. These files contain:');
-        lines.push('- Detailed explanations');
-        lines.push('- Code examples with language annotations');
-        lines.push('- Links to original documentation');
-        lines.push('- Table of contents for quick navigation\n');
-        lines.push('### scripts/');
-        lines.push('Add helper scripts here for common automation tasks.\n');
-        lines.push('### assets/');
-        lines.push('Add templates, boilerplate, or example projects here.\n');
-        // Notes
-        lines.push('## Notes\n');
-        lines.push('- This skill was automatically generated from official documentation');
-        lines.push('- Reference files preserve the structure and examples from source docs');
-        lines.push('- Code examples include language detection for better syntax highlighting');
-        lines.push('- Quick reference patterns are extracted from common usage examples in the docs\n');
+        lines.push('### Getting Started');
+        const hasTutorials = sortedCategories.some(c => c.includes('tutorial') || c.includes('getting-started') || c.includes('guide'));
+        if (hasTutorials) {
+            lines.push('Start with tutorial or getting-started reference files for foundational concepts.');
+        }
+        else {
+            lines.push('Begin with the first reference file that matches your needs.');
+        }
+        lines.push('');
+        lines.push('### Finding Specific Information');
+        lines.push('Use the category reference files based on what you need:');
+        lines.push('- **API/Reference files**: For method signatures, parameters, and return types');
+        lines.push('- **Guide/Tutorial files**: For step-by-step instructions and examples');
+        lines.push('- **Other categories**: For domain-specific documentation');
+        lines.push('');
+        // Quick Reference (if applicable)
+        lines.push('## Quick Reference\n');
+        lines.push('Common patterns and examples are included in the reference files. Load the appropriate reference file to access code examples and detailed patterns.\n');
         return lines.join('\n');
     }
+    /**
+     * Get guidance on when to read a specific category reference file
+     */
+    getWhenToReadGuidance(category) {
+        const categoryLower = category.toLowerCase();
+        const guidance = {
+            'api': 'you need API reference, method signatures, or parameter details',
+            'reference': 'you need API reference or technical specifications',
+            'tutorials': 'you want step-by-step tutorials or learning guides',
+            'tutorial': 'you want step-by-step tutorials or learning guides',
+            'guide': 'you need how-to guides or implementation instructions',
+            'getting-started': 'you are new to the technology or need foundational concepts',
+            'examples': 'you need code examples or sample implementations',
+        };
+        // Check for partial matches
+        for (const [key, value] of Object.entries(guidance)) {
+            if (categoryLower.includes(key)) {
+                return value;
+            }
+        }
+        return null;
+    }
     /**
      * Save skill to file system in proper directory structure
      * Prevents nested skill directories by checking if outputDir is already a skill directory
      */
     async saveSkill(skill, outputDir, filename) {
         // Resolve output directory to absolute path
-        const resolvedOutputDir = resolve(outputDir);
+        // If outputDir starts with '.', resolve relative to current working directory (project root)
+        // Otherwise, use resolve() which resolves relative to current working directory anyway
+        const resolvedOutputDir = outputDir.startsWith('.')
+            ? resolve(process.cwd(), outputDir)
+            : resolve(outputDir);
+        // Determine expected skill name
+        const expectedSkillName = filename
+            ? filename
+                .toLowerCase()
+                .replace(/[^a-z0-9-]/g, '-')
+                .replace(/-+/g, '-')
+                .replace(/^-|-$/g, '')
+                .substring(0, 64) || 'documentation-skill'
+            : skill.skillName.toLowerCase()
+                .replace(/[^a-z0-9-]/g, '-')
+                .replace(/-+/g, '-')
+                .replace(/^-|-$/g, '')
+                .substring(0, 64);
         // Check if outputDir is already a skill directory (contains SKILL.md)
         let skillDir;
         try {
@@ -310,22 +517,18 @@ export class SkillGenerator {
             skillDir = resolvedOutputDir;
         }
         catch {
-            // outputDir is not a skill directory, create new skill directory
-            // Sanitize filename (lowercase, hyphens only, max 64 chars)
-            let skillDirName;
-            if (filename) {
-                skillDirName = filename
-                    .toLowerCase()
-                    .replace(/[^a-z0-9-]/g, '-')
-                    .replace(/-+/g, '-')
-                    .replace(/^-|-$/g, '')
-                    .substring(0, 64) || 'documentation-skill';
+            // outputDir is not a skill directory
+            // Check if the last part of outputDir is already the skill name
+            // If so, use outputDir directly; otherwise create subdirectory
+            const outputDirBasename = basename(resolvedOutputDir);
+            if (outputDirBasename === expectedSkillName) {
+                // outputDir already ends with skill name, use it directly
+                skillDir = resolvedOutputDir;
             }
             else {
-                skillDirName = skill.skillName;
+                // Create new skill directory
+                skillDir = join(resolvedOutputDir, expectedSkillName);
             }
-            // Create skill directory
-            skillDir = join(resolvedOutputDir, skillDirName);
             await mkdir(skillDir, { recursive: true });
         }
         // Create references subdirectory
@@ -369,5 +572,71 @@ export class SkillGenerator {
     capitalize(text) {
         return text.charAt(0).toUpperCase() + text.slice(1);
     }
+    /**
+     * Check if crawled content is sufficient for skill generation
+     */
+    canGenerateSkill(pages) {
+        if (pages.length === 0) {
+            return { canGenerate: false, reason: 'empty_pages' };
+        }
+        // Check if any page has sufficient content
+        let hasSufficientContent = false;
+        let hasStructuredContent = false;
+        let hasTextContent = false;
+        let mediaOnlyCount = 0;
+        for (const page of pages) {
+            const contentLength = (page.content || '').trim().length;
+            const hasHeadings = page.headings && page.headings.length > 0;
+            const hasText = contentLength > 0;
+            // Check if page is media-only (has images but no text)
+            const hasImages = /<img[^>]*>/i.test(page.content || '');
+            const hasMedia = hasImages || (page.codeSamples && page.codeSamples.length > 0);
+            if (hasMedia && contentLength < this.MIN_CONTENT_LENGTH) {
+                mediaOnlyCount++;
+            }
+            if (contentLength >= this.MIN_CONTENT_LENGTH) {
+                hasSufficientContent = true;
+            }
+            if (hasHeadings) {
+                hasStructuredContent = true;
+            }
+            if (hasText) {
+                hasTextContent = true;
+            }
+        }
+        // All pages are media-only
+        if (mediaOnlyCount === pages.length && !hasTextContent) {
+            return { canGenerate: false, reason: 'media_only' };
+        }
+        // No pages have sufficient content
+        if (!hasSufficientContent) {
+            return { canGenerate: false, reason: 'insufficient_content' };
+        }
+        // No structured content (headings, sections)
+        if (!hasStructuredContent) {
+            return { canGenerate: false, reason: 'no_structured_content' };
+        }
+        return { canGenerate: true };
+    }
+    /**
+     * Validate description quality - checks length and presence of trigger keywords
+     */
+    validateDescription(description) {
+        // Check length
+        if (description.length > 1024) {
+            throw new Error(`Description exceeds 1024 character limit: ${description.length} characters`);
+        }
+        // Check for basic quality indicators (warnings only, don't fail)
+        const hasUseCase = /for:|when|use|working with/i.test(description);
+        const hasTriggers = /trigger|keyword|concept/i.test(description) || description.split(',').length >= 3;
+        const minLength = description.length >= 100; // At least 100 chars for meaningful description
+        // Log warnings if description seems too generic
+        if (!hasUseCase && !hasTriggers) {
+            console.warn('Description may be too generic - consider adding more specific triggers or use cases');
+        }
+        if (!minLength) {
+            console.warn('Description may be too short - consider adding more detail');
+        }
+    }
 }
 //# sourceMappingURL=skill-generator.js.map