@indiccoder/mentis-cli 1.0.8 → 1.0.9

package/dist/skills/SkillsManager.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * SkillsManager - Core module for Agent Skills system
+ * Handles discovery, loading, and validation of skills
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fast_glob_1 = require("fast-glob");
+const yaml_1 = __importDefault(require("yaml"));
+class SkillsManager {
+    constructor(cwd = process.cwd()) {
+        this.skills = new Map();
+        this.personalSkillsDir = path.join(os.homedir(), '.mentis', 'skills');
+        this.projectSkillsDir = path.join(cwd, '.mentis', 'skills');
+    }
+    /**
+     * Discover all skills from configured directories
+     */
+    async discoverSkills(options = {}) {
+        const { includePersonal = true, includeProject = true, includePlugin = false // Plugin skills not implemented yet
+         } = options;
+        const discovered = [];
+        if (includePersonal) {
+            discovered.push(...await this.discoverSkillsInDirectory(this.personalSkillsDir, 'personal'));
+        }
+        if (includeProject) {
+            discovered.push(...await this.discoverSkillsInDirectory(this.projectSkillsDir, 'project'));
+        }
+        // Store skills in map for quick lookup
+        for (const skill of discovered) {
+            this.skills.set(skill.name, skill);
+        }
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Discover skills in a specific directory
+     */
+    async discoverSkillsInDirectory(dir, type) {
+        if (!fs.existsSync(dir)) {
+            return [];
+        }
+        const skills = [];
+        try {
+            // Find all SKILL.md files in subdirectories
+            const skillFiles = await (0, fast_glob_1.glob)('**/SKILL.md', {
+                cwd: dir,
+                absolute: true,
+                onlyFiles: true
+            });
+            for (const skillFile of skillFiles) {
+                const skillDir = path.dirname(skillFile);
+                const skillName = path.basename(skillDir);
+                const skill = await this.loadSkillMetadata(skillFile, skillDir, type);
+                if (skill) {
+                    skills.push(skill);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Error discovering skills in ${dir}: ${error.message}`);
+        }
+        return skills;
+    }
+    /**
+     * Load only the metadata (YAML frontmatter) from a SKILL.md file
+     * This is used for progressive disclosure - only name/description loaded at startup
+     */
+    async loadSkillMetadata(skillPath, skillDir, type) {
+        try {
+            const content = fs.readFileSync(skillPath, 'utf-8');
+            const frontmatter = this.extractFrontmatter(content);
+            if (!frontmatter) {
+                return null;
+            }
+            // Convert SkillFrontmatter to SkillMetadata for validation
+            const metadata = {
+                name: frontmatter.name,
+                description: frontmatter.description,
+                allowedTools: frontmatter['allowed-tools']
+            };
+            const validation = this.validateSkillMetadata(metadata);
+            const skill = {
+                name: frontmatter.name,
+                description: frontmatter.description,
+                allowedTools: frontmatter['allowed-tools'],
+                path: skillPath,
+                directory: skillDir,
+                type,
+                isValid: validation.isValid,
+                errors: validation.errors.length > 0 ? validation.errors : undefined
+            };
+            return skill;
+        }
+        catch (error) {
+            console.error(`Error loading skill metadata from ${skillPath}: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Load the full content of a skill (for progressive disclosure)
+     */
+    async loadFullSkill(name) {
+        const skill = this.skills.get(name);
+        if (!skill) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(skill.path, 'utf-8');
+            skill.content = content;
+            return skill;
+        }
+        catch (error) {
+            console.error(`Error loading full skill ${name}: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Extract YAML frontmatter from markdown content
+     */
+    extractFrontmatter(content) {
+        const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+        const match = content.match(frontmatterRegex);
+        if (!match) {
+            return null;
+        }
+        try {
+            const parsed = yaml_1.default.parse(match[1]);
+            return parsed;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Validate skill metadata according to Claude Code spec
+     */
+    validateSkillMetadata(metadata) {
+        const errors = [];
+        const warnings = [];
+        // Check required fields
+        if (!metadata.name) {
+            errors.push('Missing required field: name');
+        }
+        else {
+            // Name validation: lowercase letters, numbers, hyphens only, max 64 chars
+            const nameRegex = /^[a-z0-9-]+$/;
+            if (!nameRegex.test(metadata.name)) {
+                errors.push('Name must contain only lowercase letters, numbers, and hyphens');
+            }
+            if (metadata.name.length > 64) {
+                errors.push('Name must be 64 characters or less');
+            }
+        }
+        if (!metadata.description) {
+            errors.push('Missing required field: description');
+        }
+        else {
+            if (metadata.description.length > 1024) {
+                errors.push('Description must be 1024 characters or less');
+            }
+            // Check if description mentions when to use
+            if (!metadata.description.toLowerCase().includes('use when') &&
+                !metadata.description.toLowerCase().includes('use for')) {
+                warnings.push('Description should include when to use this skill (e.g., "Use when...")');
+            }
+        }
+        // Validate allowed-tools if present
+        if (metadata.allowedTools) {
+            const validTools = [
+                'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash', 'WebSearch',
+                'GitStatus', 'GitDiff', 'GitCommit', 'GitPush', 'GitPull',
+                'ListDir', 'SearchFile', 'RunShell'
+            ];
+            const invalidTools = metadata.allowedTools.filter(t => !validTools.includes(t));
+            if (invalidTools.length > 0) {
+                warnings.push(`Unknown tools in allowed-tools: ${invalidTools.join(', ')}`);
+            }
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Get skill by name
+     */
+    getSkill(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Get all skills
+     */
+    getAllSkills() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Get skills formatted for model context injection
+     * This provides only metadata for progressive disclosure
+     */
+    getSkillsContext() {
+        const skills = this.getAllSkills().filter(s => s.isValid);
+        if (skills.length === 0) {
+            return '';
+        }
+        const context = skills.map(skill => {
+            return `- ${skill.name}: ${skill.description}`;
+        }).join('\n');
+        return `Available Skills:\n${context}`;
+    }
+    /**
+     * Get skills as SkillContext array
+     */
+    getSkillsContextArray() {
+        return this.getAllSkills()
+            .filter(s => s.isValid)
+            .map(s => ({
+            name: s.name,
+            description: s.description
+        }));
+    }
+    /**
+     * Validate all loaded skills
+     */
+    validateAllSkills() {
+        const results = new Map();
+        for (const [name, skill] of this.skills) {
+            const metadata = {
+                name: skill.name,
+                description: skill.description,
+                allowedTools: skill.allowedTools
+            };
+            results.set(name, this.validateSkillMetadata(metadata));
+        }
+        return results;
+    }
+    /**
+     * Read a supporting file from a skill directory
+     * Used for progressive disclosure of skill resources
+     */
+    readSkillFile(skillName, fileName) {
+        const skill = this.skills.get(skillName);
+        if (!skill) {
+            return null;
+        }
+        const filePath = path.join(skill.directory, fileName);
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        try {
+            return fs.readFileSync(filePath, 'utf-8');
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * List supporting files in a skill directory
+     */
+    listSkillFiles(skillName) {
+        const skill = this.skills.get(skillName);
+        if (!skill) {
+            return [];
+        }
+        if (!fs.existsSync(skill.directory)) {
+            return [];
+        }
+        try {
+            const files = fs.readdirSync(skill.directory);
+            // Exclude SKILL.md as it's the main file
+            return files.filter(f => f !== 'SKILL.md');
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    /**
+     * Create skills directories if they don't exist
+     */
+    ensureDirectoriesExist() {
+        if (!fs.existsSync(this.personalSkillsDir)) {
+            fs.mkdirSync(this.personalSkillsDir, { recursive: true });
+        }
+    }
+    /**
+     * Get personal skills directory path
+     */
+    getPersonalSkillsDir() {
+        return this.personalSkillsDir;
+    }
+    /**
+     * Get project skills directory path
+     */
+    getProjectSkillsDir() {
+        return this.projectSkillsDir;
+    }
+}
+exports.SkillsManager = SkillsManager;

package/docs/SKILLS.md

@@ -0,0 +1,319 @@
+# Agent Skills - User Guide
+
+## Overview
+
+Agent Skills allow you to package your expertise into modular, reusable capabilities that Mentis can autonomously discover and use. Skills are organized folders containing instructions, scripts, and resources that extend Mentis's functionality.
+
+## How Skills Work
+
+1. **Discovery**: Mentis scans `~/.mentis/skills/` (personal) and `.mentis/skills/` (project) for skills
+2. **Metadata Injection**: At startup, skill names and descriptions are added to the system context
+3. **Model-Invoked**: When Mentis determines a skill is relevant to your request, it automatically loads the full skill content
+4. **Progressive Disclosure**: Supporting files are only loaded when explicitly referenced
+
+## Skill Structure
+
+```
+skill-directory/
+├── SKILL.md           # Required: YAML frontmatter + instructions
+├── reference.md       # Optional: Additional documentation
+├── examples.md        # Optional: Usage examples
+├── scripts/           # Optional: Executable utilities
+│   └── helper.py
+└── templates/         # Optional: File templates
+    └── template.txt
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: your-skill-name
+description: What this skill does and when to use it
+allowed-tools: Read, Grep, Glob  # Optional: Restrict tools
+---
+
+# Your Skill Name
+
+## Instructions
+Step-by-step guidance for Mentis.
+
+## Examples
+Concrete usage examples.
+```
+
+### Required Fields
+
+- **name**: Lowercase letters, numbers, hyphens only (max 64 characters)
+- **description**: What the skill does + when to use it (max 1024 characters)
+
+### Optional Fields
+
+- **allowed-tools**: List of tools the skill can use without permission
+
+## Creating Your First Skill
+
+### Option 1: Interactive Wizard
+
+```
+/skills create
+```
+
+Follow the prompts:
+1. Enter skill name (e.g., `my-custom-skill`)
+2. Choose type (personal or project)
+3. Write description (include "Use when..." for better discovery)
+4. Optionally restrict allowed tools
+
+### Option 2: Manual Creation
+
+```bash
+# Create directory
+mkdir -p ~/.mentis/skills/my-skill
+
+# Create SKILL.md
+cat > ~/.mentis/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: Does something useful. Use when the user mentions specific keywords.
+---
+
+# My Skill
+
+## Instructions
+1. Do this first
+2. Then do that
+
+## Examples
+Example usage...
+EOF
+```
+
+## Skill Commands
+
+| Command | Description |
+|---------|-------------|
+| `/skills` | List all available skills |
+| `/skills list` | List all available skills |
+| `/skills show <name>` | Display full skill content |
+| `/skills create [name]` | Interactive skill creator |
+| `/skills validate` | Validate all skills for errors |
+
+## Skill Types
+
+### Personal Skills
+
+Stored in `~/.mentis/skills/` - available across all projects.
+
+**Use for**:
+- Individual workflows and preferences
+- Experimental skills in development
+- Personal productivity tools
+
+### Project Skills
+
+Stored in `.mentis/skills/` - shared with your team via git.
+
+**Use for**:
+- Team workflows and conventions
+- Project-specific expertise
+- Shared utilities and scripts
+
+## Best Practices
+
+### 1. Write Clear Descriptions
+
+❌ **Too vague**:
+```yaml
+description: Helps with data
+```
+
+✅ **Specific**:
+```yaml
+description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
+```
+
+**Tip**: Include both what the skill does AND when to use it.
+
+### 2. Use Progressive Disclosure
+
+Keep `SKILL.md` lean. Move detailed content to supporting files:
+
+**SKILL.md**:
+```markdown
+## Quick Start
+Basic instructions here.
+
+For advanced patterns, see [reference.md](reference.md).
+```
+
+**reference.md**:
+```markdown
+# Advanced Reference
+Detailed documentation...
+```
+
+### 3. Validate Your Skills
+
+```
+/skills validate
+```
+
+Check for:
+- Missing required fields
+- Invalid name format
+- Description length
+- Unknown tools in allowed-tools
+
+### 4. Test Skills
+
+After creating a skill:
+1. Restart Mentis to load it
+2. Ask a question that should trigger the skill
+3. Verify Mentis loads and uses the skill
+
+## Example Skills
+
+### commit-helper
+
+```yaml
+---
+name: commit-helper
+description: Generates clear, conventional commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+allowed-tools: ["GitStatus", "GitDiff", "GitCommit"]
+---
+```
+
+### code-reviewer
+
+```yaml
+---
+name: code-reviewer
+description: Reviews code for best practices, potential bugs, security issues. Use when reviewing code or checking PRs.
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+```
+
+See `examples/skills/` for complete examples.
+
+## Troubleshooting
+
+### Skill Not Loading
+
+**Check 1**: File location
+```bash
+# Personal skills
+ls ~/.mentis/skills/my-skill/SKILL.md
+
+# Project skills
+ls .mentis/skills/my-skill/SKILL.md
+```
+
+**Check 2**: YAML syntax
+```bash
+# Verify frontmatter format
+cat ~/.mentis/skills/my-skill/SKILL.md | head -n 10
+```
+
+Ensure:
+- `---` on line 1
+- `---` closes frontmatter
+- Valid YAML (no tabs, correct indentation)
+
+**Check 3**: Validation
+```bash
+/skills validate
+```
+
+### Mentis Not Using Skill
+
+**Problem**: Skill exists but Mentis doesn't invoke it.
+
+**Solution**: Improve description to include trigger keywords.
+
+❌ **Vague**:
+```yaml
+description: Code improvement
+```
+
+✅ **Clear with triggers**:
+```yaml
+description: Refactor code for better performance and readability. Use when the user mentions optimization, refactoring, performance, or code cleanup.
+```
+
+### allowed-tools Not Working
+
+**Check**: Tool names must match Mentis tool names exactly.
+
+Valid tools: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `ListDir`, `SearchFile`, `RunShell`, `WebSearch`, `GitStatus`, `GitDiff`, `GitCommit`, `GitPush`, `GitPull`
+
+## Sharing Skills
+
+### Via Git (Project Skills)
+
+```bash
+# Add to repository
+git add .mentis/skills/
+git commit -m "Add team skill for X"
+git push
+
+# Team members get it automatically
+git pull
+# Skill is now available
+```
+
+### Via Manual Copy
+
+```bash
+# Export
+tar czf my-skill.tar.gz -C ~/.mentis/skills my-skill
+
+# Import on another machine
+tar xzf my-skill.tar.gz -C ~/.mentis/skills
+```
+
+## Advanced Topics
+
+### Code Execution in Skills
+
+Skills can include executable scripts:
+
+```markdown
+## Running the Script
+
+```bash
+python scripts/analyze.py data.csv
+```
+```
+
+Mentis will execute the script and return results.
+
+### Tool Permissions
+
+Use `allowed-tools` to:
+- Restrict read-only skills from making changes
+- Limit scope of specialized skills
+- Add security for sensitive operations
+
+```yaml
+---
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+```
+
+When this skill is active, only these tools can be used without explicit permission.
+
+### Dynamic Tool Loading
+
+The model can invoke tools to load skills:
+
+```
+load_skill({ name: "pdf-processing" })
+```
+
+This loads the full SKILL.md content into context.
+
+## Resources
+
+- [Claude Code Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - Official announcement
+- [examples/skills/](../examples/skills/) - Example skills directory