@indiccoder/mentis-cli 1.0.8 → 1.0.9

package/examples/skills/code-reviewer/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: code-reviewer
+description: Reviews code for best practices, potential bugs, security issues, and improvements. Use when reviewing code, checking pull requests, or analyzing code quality.
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+
+# Code Reviewer
+
+This skill provides systematic code review to identify issues and suggest improvements.
+
+## Review Checklist
+
+### 1. Code Organization
+- [ ] Single Responsibility Principle followed
+- [ ] Clear and descriptive names
+- [ ] Proper separation of concerns
+- [ ] Appropriate abstraction levels
+
+### 2. Error Handling
+- [ ] Proper error handling for all operations
+- [ ] Meaningful error messages
+- [ ] Graceful degradation
+- [ ] No silent failures
+
+### 3. Performance
+- [ ] No obvious performance issues
+- [ ] Appropriate data structures used
+- [ ] Caching where applicable
+- [ ] Resource cleanup (no memory leaks)
+
+### 4. Security
+- [ ] Input validation
+- [ ] No hardcoded credentials
+- [ ] SQL injection prevention
+- [ ] XSS prevention (web apps)
+- [ ] Proper authentication/authorization
+
+### 5. Testing
+- [ ] Test coverage adequate
+- [ ] Edge cases considered
+- [ ] Error scenarios tested
+
+### 6. Documentation
+- [ ] Complex logic explained
+- [ ] Public API documented
+- [ ] Usage examples provided
+
+## How to Review
+
+1. **Understand the purpose**: What is this code supposed to do?
+2. **Read the code**: Follow the execution flow
+3. **Check against checklist**: Go through each category
+4. **Provide feedback**:
+   - **Critical**: Must fix before merge
+   - **Important**: Should fix
+   - **Suggestion**: Nice to have
+5. **Explain why**: Don't just point out problems
+
+## Feedback Format
+
+```markdown
+## Critical Issues
+- Issue description
+  - Location: file.ts:123
+  - Why: [reason]
+  - Suggestion: [fix]
+
+## Important Notes
+- Note description
+  - Location: file.ts:456
+
+## Suggestions
+- Suggestion description
+  - Could improve [aspect]
+```
+
+## Common Issues to Look For
+
+| Issue | Example |
+|-------|---------|
+| Unhandled promises | No `.catch()` or `await` without try/catch |
+| Missing null checks | Accessing properties without null check |
+| Race conditions | Async operations without proper ordering |
+| Resource leaks | File handles, connections not closed |
+| Type coercion | Using `==` instead of `===` |
+| Magic numbers | Unexplained numeric literals |
+| Large functions | Functions > 50 lines |
+| Deep nesting | More than 3 levels of nesting |

package/examples/skills/commit-helper/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: commit-helper
+description: Generates clear, conventional commit messages from git diffs. Use when writing commit messages, reviewing staged changes, or when the user asks for help with git commits.
+allowed-tools: ["GitStatus", "GitDiff", "GitCommit"]
+---
+
+# Commit Message Helper
+
+This skill helps you write clear, informative git commit messages following conventional commit format.
+
+## Instructions
+
+When the user wants to commit changes:
+
+1. **Check git status** to see what files are staged
+2. **Review the diff** to understand what changed
+3. **Generate a commit message** with:
+   - **Type**: One of `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+   - **Scope**: (optional) The component or module affected
+   - **Summary**: Brief description under 50 characters
+   - **Body**: Detailed explanation of what and why (not how)
+   - **Footer**: (optional) Breaking changes or references
+
+## Commit Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation changes |
+| `style` | Code style changes (formatting, etc.) |
+| `refactor` | Code refactoring |
+| `test` | Adding or updating tests |
+| `chore` | Maintenance tasks |
+
+## Examples
+
+### Feature Addition
+```
+feat(api): add user authentication endpoint
+
+Add OAuth2 authentication for the REST API.
+Implements login, logout, and token refresh.
+```
+
+### Bug Fix
+```
+fix(cli): prevent crash when config file is missing
+
+Check for config file existence before reading.
+Show helpful error message if file not found.
+```
+
+### Documentation
+```
+docs: update README with new installation instructions
+
+Clarify NPM installation steps and add troubleshooting section.
+```
+
+## Best Practices
+
+- Use present tense ("add" not "added")
+- Explain what and why, not how
+- Keep summary under 50 characters
+- Reference issues in footer: `Closes #123`

package/examples/skills/pdf-processing/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pdf-processing
+description: Extract text, fill forms, merge PDFs, and manipulate PDF documents. Use when working with PDF files, forms, or document extraction. Requires pdf-parse package.
+---
+
+# PDF Processing
+
+This skill provides PDF manipulation capabilities for text extraction, form filling, and document operations.
+
+## Prerequisites
+
+Install required packages:
+```bash
+npm install pdf-parse
+# or
+pnpm add pdf-parse
+# or
+yarn add pdf-parse
+```
+
+## Capabilities
+
+### 1. Text Extraction
+Extract plain text from PDF files with page-by-page information.
+
+### 2. Form Field Detection
+Identify and extract form fields from PDF documents.
+
+### 3. Metadata Reading
+Access PDF metadata like author, creation date, title.
+
+### 4. Page Count & Info
+Get total pages and document dimensions.
+
+## Common Operations
+
+### Extract All Text
+```typescript
+import fs from 'fs';
+import pdf from 'pdf-parse';
+
+const dataBuffer = fs.readFileSync('document.pdf');
+const data = await pdf(dataBuffer);
+
+console.log(data.text);        // Full text content
+console.log(data.numpages);    // Number of pages
+console.log(data.info);        // PDF metadata
+```
+
+### Extract Text by Page
+```typescript
+const data = await pdf(dataBuffer);
+// Text includes page breaks
+// Split by page markers if needed
+```
+
+### Get PDF Info
+```typescript
+const data = await pdf(dataBuffer);
+console.log({
+    pages: data.numpages,
+    info: data.info,
+    metadata: data.metadata
+});
+```
+
+## Troubleshooting
+
+### "pdf-parse not found"
+Install the package: `npm install pdf-parse`
+
+### Scanned PDFs return no text
+Scanned PDFs are images. Use OCR (tesseract.js) instead.
+
+### Encrypted PDFs
+Password-protected PDFs cannot be read. Remove password first.
+
+### Memory Issues with Large Files
+For very large PDFs (>100MB), process in chunks or use streaming.
+
+## Advanced Topics
+
+For advanced PDF operations like filling forms, merging, or creating PDFs, see [ADVANCED.md](ADVANCED.md).
+
+## Examples
+
+### Quick Text Extraction
+```bash
+# User asks: "Extract text from this PDF"
+# 1. Read the PDF file
+# 2. Use pdf-parse to extract text
+# 3. Return the text content
+```
+
+### Get Page Count
+```bash
+# User asks: "How many pages in this PDF?"
+# 1. Parse the PDF
+# 2. Return numpages value
+```
+
+### Form Analysis
+```bash
+# User asks: "What fields are in this PDF form?"
+# 1. Parse the PDF
+# 2. Look for form field patterns
+# 3. List detected fields
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiccoder/mentis-cli",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "publishConfig": {
     "access": "public"
   },
@@ -50,7 +50,8 @@
     "screenshot-desktop": "^1.15.3",
     "uuid": "^13.0.0",
     "vscode-ripgrep": "^1.13.2",
-    "xlsx": "^0.18.5"
+    "xlsx": "^0.18.5",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
     "@types/figlet": "^1.7.0",

package/src/repl/ReplManager.ts

@@ -17,6 +17,8 @@ import { Tool } from '../tools/Tool';
 import { McpClient } from '../mcp/McpClient';
 
 import { CheckpointManager } from '../checkpoint/CheckpointManager';
+import { SkillsManager } from '../skills/SkillsManager';
+import { LoadSkillTool, ListSkillsTool, ReadSkillFileTool } from '../skills/LoadSkillTool';
 import * as readline from 'readline';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,18 +33,23 @@ export class ReplManager {
     private modelClient!: ModelClient;
     private contextManager: ContextManager;
     private checkpointManager: CheckpointManager;
+    private skillsManager: SkillsManager;
     private history: ChatMessage[] = [];
     private mode: 'PLAN' | 'BUILD' = 'BUILD';
     private tools: Tool[] = [];
     private mcpClients: McpClient[] = [];
     private shell: PersistentShell;
     private currentModelName: string = 'Unknown';
+    private activeSkill: string | null = null;  // Track currently active skill for allowed-tools
 
     constructor() {
         this.configManager = new ConfigManager();
         this.contextManager = new ContextManager();
         this.checkpointManager = new CheckpointManager();
+        this.skillsManager = new SkillsManager();
         this.shell = new PersistentShell();
+
+        // Create tools array without skill tools first
         this.tools = [
             new WriteFileTool(),
             new ReadFileTool(),
@@ -64,6 +71,67 @@ export class ReplManager {
         });
         // Default to Ollama if not specified, assuming compatible endpoint
         this.initializeClient();
+
+        // Initialize skills system after client is ready
+        this.initializeSkills();
+    }
+
+    /**
+     * Initialize the skills system
+     */
+    private async initializeSkills() {
+        this.skillsManager.ensureDirectoriesExist();
+        await this.skillsManager.discoverSkills();
+
+        // Add skill tools to the tools list
+        // Pass callback to LoadSkillTool to track active skill
+        this.tools.push(
+            new LoadSkillTool(this.skillsManager, (skill) => {
+                this.activeSkill = skill ? skill.name : null;
+            }),
+            new ListSkillsTool(this.skillsManager),
+            new ReadSkillFileTool(this.skillsManager)
+        );
+    }
+
+    /**
+     * Check if a tool is allowed by the currently active skill
+     * Returns true if tool is allowed, false if it requires confirmation
+     */
+    private isToolAllowedBySkill(toolName: string): boolean {
+        if (!this.activeSkill) {
+            // No active skill, all tools require confirmation as per normal flow
+            return false;
+        }
+
+        const skill = this.skillsManager.getSkill(this.activeSkill);
+        if (!skill || !skill.allowedTools || skill.allowedTools.length === 0) {
+            // No skill or no allowed-tools restriction
+            return false;
+        }
+
+        // Map tool names to allowed tool names
+        const toolMapping: Record<string, string> = {
+            'write_file': 'Write',
+            'read_file': 'Read',
+            'edit_file': 'Edit',
+            'search_files': 'Grep',
+            'list_dir': 'ListDir',
+            'search_file': 'SearchFile',
+            'run_shell': 'RunShell',
+            'web_search': 'WebSearch',
+            'git_status': 'GitStatus',
+            'git_diff': 'GitDiff',
+            'git_commit': 'GitCommit',
+            'git_push': 'GitPush',
+            'git_pull': 'GitPull',
+            'load_skill': 'Read',
+            'list_skills': 'Read',
+            'read_skill_file': 'Read'
+        };
+
+        const mappedToolName = toolMapping[toolName] || toolName;
+        return skill.allowedTools.includes(mappedToolName);
     }
 
     private initializeClient() {
@@ -184,11 +252,10 @@ export class ReplManager {
                 console.log('  /drop <file> - Remove file from context');
                 console.log('  /plan    - Switch to PLAN mode');
                 console.log('  /build   - Switch to BUILD mode');
-                console.log('  /plan    - Switch to PLAN mode');
-                console.log('  /build   - Switch to BUILD mode');
                 console.log('  /model   - Interactively select Provider & Model');
                 console.log('  /use <provider> [model] - Quick switch (legacy)');
                 console.log('  /mcp <cmd> - Manage MCP servers');
+                console.log('  /skills <list|show|create|validate> - Manage Agent Skills');
                 console.log('  /resume  - Resume last session');
                 console.log('  /checkpoint <save|load|list> [name] - Manage checkpoints');
                 console.log('  /search <query> - Search codebase');
@@ -263,6 +330,9 @@ export class ReplManager {
                 const updater = new UpdateManager();
                 await updater.checkAndPerformUpdate(true);
                 break;
+            case '/skills':
+                await this.handleSkillsCommand(args);
+                break;
             default:
                 console.log(chalk.red(`Unknown command: ${command}`));
         }
@@ -270,6 +340,7 @@ export class ReplManager {
 
     private async handleChat(input: string) {
         const context = this.contextManager.getContextString();
+        const skillsContext = this.skillsManager.getSkillsContext();
         let fullInput = input;
 
         let modeInstruction = '';
@@ -281,6 +352,11 @@ export class ReplManager {
 
         fullInput = `${input}${modeInstruction}`;
 
+        // Add skills context if available
+        if (skillsContext) {
+            fullInput = `${skillsContext}\n\n${fullInput}`;
+        }
+
         if (context) {
             fullInput = `${context}\n\nUser Question: ${fullInput}`;
         }
@@ -343,7 +419,8 @@ export class ReplManager {
                     console.log(chalk.dim(`  [Action] ${toolName}(${displayArgs})`));
 
                     // Safety check for write_file
-                    if (toolName === 'write_file') {
+                    // Skip confirmation if tool is allowed by active skill
+                    if (toolName === 'write_file' && !this.isToolAllowedBySkill('Write')) {
                         // Pause cancellation listener during user interaction
                         if (process.stdin.isTTY) {
                             process.stdin.removeListener('keypress', keyListener);
@@ -863,6 +940,100 @@ export class ReplManager {
         }
     }
 
+    private async handleSkillsCommand(args: string[]) {
+        const { SkillCreator, validateSkills } = await import('../skills/SkillCreator');
+
+        if (args.length < 1) {
+            // Show skills list by default
+            await this.handleSkillsCommand(['list']);
+            return;
+        }
+
+        const action = args[0];
+
+        switch (action) {
+            case 'list':
+                await this.handleSkillsList();
+                break;
+            case 'show':
+                if (args.length < 2) {
+                    console.log(chalk.red('Usage: /skills show <name>'));
+                    return;
+                }
+                await this.handleSkillsShow(args[1]);
+                break;
+            case 'create':
+                const creator = new SkillCreator(this.skillsManager);
+                await creator.run(args[1]);
+                // Re-discover skills after creation
+                await this.skillsManager.discoverSkills();
+                break;
+            case 'validate':
+                await validateSkills(this.skillsManager);
+                break;
+            default:
+                console.log(chalk.red(`Unknown skills action: ${action}`));
+                console.log(chalk.yellow('Available actions: list, show, create, validate'));
+        }
+    }
+
+    private async handleSkillsList(): Promise<void> {
+        const skills = this.skillsManager.getAllSkills();
+
+        if (skills.length === 0) {
+            console.log(chalk.yellow('No skills available.'));
+            console.log(chalk.dim('Create skills with: /skills create'));
+            console.log(chalk.dim('Add skills to: ~/.mentis/skills/ or .mentis/skills/'));
+            return;
+        }
+
+        console.log(chalk.cyan(`\nAvailable Skills (${skills.length}):\n`));
+
+        for (const skill of skills) {
+            const statusIcon = skill.isValid ? '✓' : '✗';
+            const typeLabel = skill.type === 'personal' ? 'Personal' : 'Project';
+
+            console.log(`${statusIcon} ${chalk.bold(skill.name)} (${typeLabel})`);
+            console.log(`  ${skill.description}`);
+
+            if (skill.allowedTools && skill.allowedTools.length > 0) {
+                console.log(chalk.dim(`  Allowed tools: ${skill.allowedTools.join(', ')}`));
+            }
+
+            if (!skill.isValid && skill.errors) {
+                console.log(chalk.red(`  Errors: ${skill.errors.join(', ')}`));
+            }
+
+            console.log('');
+        }
+    }
+
+    private async handleSkillsShow(name: string): Promise<void> {
+        const skill = await this.skillsManager.loadFullSkill(name);
+
+        if (!skill) {
+            console.log(chalk.red(`Skill "${name}" not found.`));
+            return;
+        }
+
+        console.log(chalk.cyan(`\n# ${skill.name}\n`));
+        console.log(chalk.dim(`Type: ${skill.type}`));
+        console.log(chalk.dim(`Path: ${skill.path}`));
+
+        if (skill.allowedTools && skill.allowedTools.length > 0) {
+            console.log(chalk.dim(`Allowed tools: ${skill.allowedTools.join(', ')}`));
+        }
+
+        console.log('');
+        console.log(skill.content || 'No content available');
+
+        // List supporting files
+        const files = this.skillsManager.listSkillFiles(name);
+        if (files.length > 0) {
+            console.log(chalk.dim(`\nSupporting files: ${files.join(', ')}`));
+        }
+    }
+
     private estimateCost(input: number, output: number): number {
         const config = this.configManager.getConfig();
         const provider = config.defaultProvider;

package/src/skills/LoadSkillTool.ts

@@ -0,0 +1,168 @@
+/**
+ * LoadSkillTool - Tool for model-invoked skill loading
+ * The model can call this tool when it determines a skill is relevant to the current task
+ */
+
+import { Tool } from '../tools/Tool';
+import { SkillsManager, Skill } from './SkillsManager';
+
+interface LoadSkillArgs {
+    name: string;
+}
+
+type SkillLoadedCallback = (skill: Skill | null) => void;
+
+export class LoadSkillTool implements Tool {
+    name = 'load_skill';
+    description = 'Load the full content of a skill by name. Use this when you need detailed instructions from a skill. Available skills can be seen in the system prompt. Example: load_skill({ name: "commit-helper" })';
+    parameters = {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'The name of the skill to load (e.g., "commit-helper", "pdf-processing")'
+            }
+        },
+        required: ['name']
+    };
+
+    private skillsManager: SkillsManager;
+    private onSkillLoaded?: SkillLoadedCallback;
+
+    constructor(skillsManager: SkillsManager, onSkillLoaded?: SkillLoadedCallback) {
+        this.skillsManager = skillsManager;
+        this.onSkillLoaded = onSkillLoaded;
+    }
+
+    async execute(args: LoadSkillArgs): Promise<string> {
+        const { name } = args;
+
+        if (!name) {
+            return 'Error: Skill name is required';
+        }
+
+        const skill = this.skillsManager.getSkill(name);
+        if (!skill) {
+            const availableSkills = this.skillsManager.getAllSkills().map(s => s.name).join(', ');
+            return `Error: Skill "${name}" not found. Available skills: ${availableSkills || 'none'}`;
+        }
+
+        // Load full skill content
+        const fullSkill = await this.skillsManager.loadFullSkill(name);
+        if (!fullSkill || !fullSkill.content) {
+            return `Error: Failed to load content for skill "${name}"`;
+        }
+
+        // Notify callback that skill was loaded
+        if (this.onSkillLoaded) {
+            this.onSkillLoaded(fullSkill);
+        }
+
+        // Format response with skill content
+        let response = `# Loaded Skill: ${skill.name}\n\n`;
+        response += `**Type**: ${skill.type}\n`;
+        response += `**Description**: ${skill.description}\n`;
+        if (skill.allowedTools && skill.allowedTools.length > 0) {
+            response += `**Allowed Tools**: ${skill.allowedTools.join(', ')}\n`;
+        }
+        response += `\n---\n\n`;
+        response += fullSkill.content;
+
+        return response;
+    }
+}
+
+/**
+ * ListSkillsTool - Tool for listing available skills
+ */
+export class ListSkillsTool implements Tool {
+    name = 'list_skills';
+    description = 'List all available skills with their descriptions. Use this to see what skills are available.';
+    parameters = {
+        type: 'object',
+        properties: {},
+        required: []
+    };
+
+    private skillsManager: SkillsManager;
+
+    constructor(skillsManager: SkillsManager) {
+        this.skillsManager = skillsManager;
+    }
+
+    async execute(): Promise<string> {
+        const skills = this.skillsManager.getAllSkills();
+
+        if (skills.length === 0) {
+            return 'No skills available. Add skills to ~/.mentis/skills/ or .mentis/skills/';
+        }
+
+        let response = `# Available Skills (${skills.length})\n\n`;
+
+        for (const skill of skills) {
+            const statusIcon = skill.isValid ? '✓' : '✗';
+            response += `**${statusIcon} ${skill.name}** (${skill.type})\n`;
+            response += `  ${skill.description}\n`;
+
+            if (skill.allowedTools && skill.allowedTools.length > 0) {
+                response += `  Allowed tools: ${skill.allowedTools.join(', ')}\n`;
+            }
+
+            if (!skill.isValid && skill.errors) {
+                response += `  Errors: ${skill.errors.join(', ')}\n`;
+            }
+
+            response += '\n';
+        }
+
+        return response;
+    }
+}
+
+/**
+ * ReadSkillFileTool - Tool for reading supporting files within a skill
+ * Used for progressive disclosure of skill resources
+ */
+export class ReadSkillFileTool implements Tool {
+    name = 'read_skill_file';
+    description = 'Read a supporting file from within a skill directory. Use this when a skill references additional files like [reference.md](reference.md). Example: read_skill_file({ skill: "pdf-processing", file: "reference.md" })';
+    parameters = {
+        type: 'object',
+        properties: {
+            skill: {
+                type: 'string',
+                description: 'The name of the skill'
+            },
+            file: {
+                type: 'string',
+                description: 'The filename within the skill directory (e.g., "reference.md", "examples.md")'
+            }
+        },
+        required: ['skill', 'file']
+    };
+
+    private skillsManager: SkillsManager;
+
+    constructor(skillsManager: SkillsManager) {
+        this.skillsManager = skillsManager;
+    }
+
+    async execute(args: { skill: string; file: string }): Promise<string> {
+        const { skill, file } = args;
+
+        if (!skill || !file) {
+            return 'Error: Both skill and file parameters are required';
+        }
+
+        const content = this.skillsManager.readSkillFile(skill, file);
+        if (content === null) {
+            const availableFiles = this.skillsManager.listSkillFiles(skill);
+            if (availableFiles.length === 0) {
+                return `Error: Skill "${skill}" has no supporting files`;
+            }
+            return `Error: File "${file}" not found in skill "${skill}". Available files: ${availableFiles.join(', ')}`;
+        }
+
+        return content;
+    }
+}