@indiccoder/mentis-cli 1.0.5 → 1.0.9

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

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.5",
+  "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/index.ts

@@ -2,6 +2,13 @@
 import { ReplManager } from './repl/ReplManager';
 
 async function main() {
+    if (process.argv.includes('update')) {
+        const { UpdateManager } = require('./utils/UpdateManager');
+        const updater = new UpdateManager();
+        await updater.checkAndPerformUpdate(true);
+        return;
+    }
+
     const repl = new ReplManager();
     await repl.start();
 }