@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/docs/skills/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,145 @@
+# PoolBot Skills System - Implementation Summary
+
+## Completed Work
+
+### Phase 1: Core Skills System ✅
+
+We have successfully implemented a complete modular skill management system in `src/skills/` with the following components:
+
+| File | Purpose | Lines | Status |
+|------|---------|-------|--------|
+| `types.ts` | Type definitions (agentskills.io compatible) | 287 | ✅ Complete |
+| `parser.ts` | SKILL.md parser with YAML frontmatter | 211 | ✅ Complete |
+| `registry.ts` | Skills registry with EventEmitter | 205 | ✅ Complete |
+| `loader.ts` | Progressive disclosure loader | 284 | ✅ Complete |
+| `security.ts` | Security scanner (prompt injection, etc.) | 287 | ✅ Complete |
+| `commands.ts` | CLI commands (`poolbot mods`) | 462 | ✅ Complete |
+| `index.ts` | Public API exports | 295 | ✅ Complete |
+| `index.test.ts` | Comprehensive tests | 803 | ✅ 52/52 Passing |
+
+### Key Features Implemented
+
+1. **SKILL.md Parser**
+   - YAML frontmatter parsing
+   - Section-based content extraction
+   - Linked file resolution
+   - Metadata validation
+
+2. **Skills Registry**
+   - CRUD operations for skills
+   - Event-driven architecture
+   - Search with filtering
+   - Statistics and health monitoring
+
+3. **Progressive Disclosure Loader**
+   - Multiple disclosure levels: `metadata`, `summary`, `standard`, `full`
+   - Token-aware content loading
+   - Query-based content selection
+   - Linked file inclusion
+
+4. **Security Scanner**
+   - Prompt injection detection
+   - Command injection detection
+   - Path traversal detection
+   - Hardcoded credential detection
+   - Pattern-based vulnerability scanning
+
+5. **CLI Commands**
+   - `poolbot mods list` - List all skills
+   - `poolbot mods view <id>` - View skill details
+   - `poolbot mods search <query>` - Search skills
+   - `poolbot mods enable <id>` - Enable a skill
+   - `poolbot mods disable <id>` - Disable a skill
+   - `poolbot mods scan` - Scan for new skills
+   - `poolbot mods stats` - Show statistics
+
+### Test Coverage
+
+```
+✓ Parser (13 tests)
+  - YAML parsing
+  - Metadata validation
+  - Skill file detection
+
+✓ Registry (17 tests)
+  - Scanning
+  - CRUD operations
+  - Enable/disable
+  - Search
+  - Statistics
+  - Events
+
+✓ Loader (10 tests)
+  - Disclosure levels
+  - Context preparation
+  - Token limits
+  - Linked files
+  - Query-based loading
+
+✓ Security (10 tests)
+  - Full scanning
+  - Quick checks
+  - Summary generation
+
+✓ Integration (2 tests)
+  - Full workflow
+  - Security workflow
+```
+
+### Build Status
+
+```bash
+$ pnpm build
+✅ TypeScript compilation successful
+✅ All build steps completed
+```
+
+### Integration Architecture Plan
+
+Created comprehensive integration plan at `docs/integrations/INTEGRATION_PLAN.md` covering:
+
+1. **Page Agent Integration** - Browser automation enhancement
+2. **HexStrike AI Integration** - Security platform (150+ tools)
+3. **xyOps Integration** - Workflow automation platform
+
+The plan includes:
+- Architecture diagrams
+- Implementation phases (6 weeks)
+- Configuration schemas
+- Security considerations
+- Risk mitigation strategies
+
+### Files Created
+
+```
+src/skills/
+├── types.ts           # Core type definitions
+├── parser.ts          # SKILL.md parser
+├── registry.ts        # Skills registry
+├── loader.ts          # Progressive disclosure loader
+├── security.ts        # Security scanner
+├── commands.ts        # CLI commands
+├── index.ts           # Public API
+└── index.test.ts      # Tests
+
+docs/skills/
+└── SKILL.md           # Skill authoring guide
+
+docs/integrations/
+└── INTEGRATION_PLAN.md # Integration architecture plan
+```
+
+### Next Steps
+
+The skills system is production-ready. To proceed with integrations:
+
+1. Review `docs/integrations/INTEGRATION_PLAN.md`
+2. Prioritize which integration to implement first
+3. Begin Phase 1 of the integration plan
+
+### Notes
+
+- Context engine integration was removed to avoid circular dependencies
+- This will be implemented in a future phase as a separate module
+- All existing PoolBot functionality remains intact
+- No breaking changes introduced

package/docs/skills/SKILL.md

@@ -0,0 +1,524 @@
+---
+id: poolbot-skills-system
+name: PoolBot Skills System
+description: |
+  Comprehensive documentation for the PoolBot skills system.
+  Covers creating, managing, and using skills with the new modular architecture.
+version: 1.0.0
+author: PoolBot Team
+categories:
+  - documentation
+  - skills
+tags:
+  - reference
+  - guide
+metadata:
+  poolbot:
+    emoji: 📖
+    always: false
+---
+
+# PoolBot Skills System
+
+The PoolBot Skills System provides a modular way to extend PoolBot's capabilities through declarative SKILL.md files.
+
+## Overview
+
+Skills are self-contained capabilities defined in markdown files following the [agentskills.io](https://agentskills.io) specification. They support:
+
+- **Progressive Disclosure**: Content loads incrementally (metadata → summary → full)
+- **Security Scanning**: Automatic detection of prompt injection, command injection, etc.
+- **Context Integration**: Skills can be injected into LLM prompts
+- **CLI Management**: List, search, enable/disable skills via `poolbot mods`
+
+## Quick Start
+
+### Listing Skills
+
+```bash
+# List all skills
+poolbot mods list
+
+# Filter by category
+poolbot mods list --category=productivity
+
+# Show only enabled/disabled
+poolbot mods list --enabled
+```
+
+### Viewing Skills
+
+```bash
+# View skill summary (default)
+poolbot mods view coding-agent
+
+# View full content
+poolbot mods view coding-agent --full
+
+# View just metadata
+poolbot mods view coding-agent --metadata
+```
+
+### Searching Skills
+
+```bash
+# Search by text
+poolbot mods search git
+
+# Search with filters
+poolbot mods search api --category=development
+```
+
+### Managing Skills
+
+```bash
+# Enable a skill
+poolbot mods enable github
+
+# Disable a skill
+poolbot mods disable spotify
+
+# Security scan
+poolbot mods scan
+
+# Statistics
+poolbot mods stats
+```
+
+## Creating Skills
+
+### File Structure
+
+```
+skills/
+└── my-skill/
+    └── SKILL.md          # Main skill definition
+```
+
+### SKILL.md Format
+
+```markdown
+---
+id: my-skill              # Unique kebab-case identifier
+name: My Skill            # Human-readable name
+description: |            # Multi-line description
+  What this skill does.
+  Can span multiple lines.
+version: 1.0.0            # Semver version
+author: Your Name         # Author attribution
+categories:               # Classification
+  - category1
+  - category2
+tags:                     # Searchable tags
+  - tag1
+  - tag2
+metadata:
+  poolbot:                # PoolBot-specific settings
+    emoji: 🚀
+    always: false         # Load on every session?
+    requires:             # Dependencies
+      bins: [gh, jq]
+      env: [GITHUB_TOKEN]
+    install:              # Auto-install specs
+      - kind: brew
+        formula: gh
+        bins: [gh]
+---
+
+# My Skill
+
+## When to Use
+
+✅ **USE this skill when:**
+- Condition 1
+- Condition 2
+
+❌ **DON'T use this skill when:**
+- Condition 3
+- Condition 4
+
+## Overview
+
+Description of what this skill does.
+
+## Common Commands
+
+```bash
+# Example command
+command here
+```
+
+## Templates
+
+Provide reusable templates.
+```
+
+### Required Sections
+
+1. **Frontmatter** (YAML between `---` markers)
+2. **When to Use** - Clear usage guidelines
+3. **Overview** - What the skill does
+
+### Optional Sections
+
+- **Common Commands** - Practical examples
+- **Templates** - Reusable code snippets
+- **Configuration** - Setup instructions
+- **Troubleshooting** - Common issues
+
+## Security
+
+Skills are automatically scanned for:
+
+- **Prompt injection** attempts
+- **Command injection** patterns
+- **Path traversal** attacks
+- **Hardcoded credentials**
+- **Suspicious encoding**
+- **Data exfiltration** endpoints
+
+### Security Levels
+
+```typescript
+enum SecurityLevel {
+  STRICT = "strict",    // Reject any suspicious patterns
+  BALANCED = "balanced", // Warn but allow with review
+  PERMISSIVE = "permissive" // Minimal checks
+}
+```
+
+### Best Practices
+
+1. Never include hardcoded credentials
+2. Use environment variables for secrets
+3. Validate all user inputs
+4. Review skills before enabling
+5. Run `poolbot mods scan` regularly
+
+## Progressive Disclosure
+
+Skills load content incrementally to manage token usage:
+
+### Disclosure Levels
+
+1. **Metadata** (~50-200 tokens)
+   - ID, name, description
+   - Categories and tags
+   - Basic info
+
+2. **Summary** (~200-1000 tokens)
+   - "When to Use" section
+   - "Overview" section
+   - Key commands
+
+3. **Full** (all content)
+   - Complete markdown
+   - All sections
+   - Linked files
+
+### Loading for Queries
+
+```typescript
+// Load skills relevant to a query
+const skills = await loader.loadForQuery("How do I create a GitHub PR?", {
+  maxSkills: 3,
+  maxTokens: 2000
+});
+```
+
+## Context Integration
+
+Skills can be injected into LLM prompts:
+
+```typescript
+import { prepareSkillsForContext } from "./skills/index.js";
+
+// Prepare skills for context injection
+const context = await prepareSkillsForContext({
+  skillIds: ["github", "git"],
+  disclosure: "summary",
+  maxTokens: 2000
+});
+
+// Inject into prompt
+const prompt = `${context}\n\nUser: How do I create a PR?`;
+```
+
+### Auto-Loading
+
+Skills with `metadata.poolbot.always: true` are automatically loaded in every session.
+
+## CLI Reference
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `poolbot mods list` | List all skills |
+| `poolbot mods view <id>` | View skill details |
+| `poolbot mods search <query>` | Search skills |
+| `poolbot mods enable <id>` | Enable a skill |
+| `poolbot mods disable <id>` | Disable a skill |
+| `poolbot mods scan [path]` | Security scan |
+| `poolbot mods stats` | Show statistics |
+
+### Options
+
+**List:**
+- `--category <cat>` - Filter by category
+- `--tag <tag>` - Filter by tag
+- `--enabled` - Show only enabled
+- `--disabled` - Show only disabled
+
+**View:**
+- `--metadata` - Show only metadata
+- `--summary` - Show metadata + summary
+- `--full` - Show full content
+
+**Search:**
+- `--category <cat>` - Filter by category
+- `--tag <tag>` - Filter by tag
+
+## Architecture
+
+### Components
+
+```
+skills/
+├── types.ts      # Type definitions
+├── parser.ts     # SKILL.md parser
+├── registry.ts   # Skills registry
+├── loader.ts     # Progressive disclosure loader
+├── security.ts   # Security scanner
+├── commands.ts   # CLI commands
+└── index.ts      # Public API
+```
+
+### Data Flow
+
+1. **Discovery**: Registry scans `skills/` directory
+2. **Parsing**: Parser extracts metadata and content
+3. **Security**: Scanner checks for vulnerabilities
+4. **Loading**: Loader provides progressive disclosure
+5. **Integration**: Skills injected into context
+
+### Registry Events
+
+```typescript
+registry.on("skillLoaded", ({ skill }) => {
+  console.log(`Loaded: ${skill.name}`);
+});
+
+registry.on("skillEnabled", ({ skillId }) => {
+  console.log(`Enabled: ${skillId}`);
+});
+```
+
+## API Reference
+
+### Types
+
+```typescript
+interface Skill {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  author?: string;
+  categories: string[];
+  tags: string[];
+  metadata?: SkillMetadata;
+  content: SkillContent;
+  source: SkillSource;
+}
+
+interface SkillContent {
+  full: string;
+  summary?: string;
+  sections: SkillSection[];
+}
+```
+
+### Functions
+
+```typescript
+// Initialize
+import { initSkills } from "./skills/index.js";
+await initSkills();
+
+// Registry
+import { getRegistry } from "./skills/index.js";
+const registry = getRegistry();
+
+// Loading
+import { createSkillLoader } from "./skills/index.js";
+const loader = createSkillLoader(registry);
+
+// Security
+import { scanSkill } from "./skills/index.js";
+const report = await scanSkill(skill);
+```
+
+## Examples
+
+### Basic Skill
+
+```markdown
+---
+id: hello-world
+name: Hello World
+description: A simple example skill
+version: 1.0.0
+categories:
+  - examples
+tags:
+  - demo
+---
+
+# Hello World
+
+## When to Use
+
+Use this skill to learn the basics.
+
+## Overview
+
+This is a minimal example.
+```
+
+### Skill with Dependencies
+
+```markdown
+---
+id: github-pr
+name: GitHub PR Helper
+description: Create and manage GitHub PRs
+version: 1.2.0
+categories:
+  - development
+  - git
+tags:
+  - github
+  - pr
+  - automation
+metadata:
+  poolbot:
+    emoji: 🔄
+    requires:
+      bins: [gh]
+      env: [GITHUB_TOKEN]
+---
+
+# GitHub PR Helper
+
+## When to Use
+
+✅ Creating PRs, reviewing code, managing branches
+❌ Non-Git repositories
+
+## Overview
+
+Streamlines GitHub PR workflows.
+
+## Common Commands
+
+```bash
+# Create PR
+gh pr create --title "feat: add feature" --body "Description"
+
+# List PRs
+gh pr list
+```
+```
+
+### Skill with Linked Files
+
+```markdown
+---
+id: advanced-api
+name: Advanced API
+description: Complex API integration
+version: 2.0.0
+categories:
+  - api
+tags:
+  - advanced
+---
+
+# Advanced API
+
+See [Authentication](./auth.md) for setup.
+Check [Examples](./examples/) for more.
+```
+
+## Troubleshooting
+
+### Skill Not Found
+
+```bash
+# Check if file exists
+ls skills/my-skill/SKILL.md
+
+# Verify frontmatter
+head -20 skills/my-skill/SKILL.md
+```
+
+### Parse Errors
+
+```bash
+# Validate YAML frontmatter
+poolbot mods scan skills/my-skill
+```
+
+### Security Warnings
+
+```bash
+# Review security report
+poolbot mods scan skills/my-skill --verbose
+```
+
+## Migration Guide
+
+### From Legacy Skills
+
+1. Rename `skill.md` to `SKILL.md`
+2. Add YAML frontmatter
+3. Update to agentskills.io format
+4. Run security scan
+5. Test with `poolbot mods view`
+
+## Best Practices
+
+1. **Clear IDs**: Use descriptive kebab-case IDs
+2. **Versioning**: Use semantic versioning
+3. **Categories**: Choose from standard categories
+4. **Tags**: Add relevant searchable tags
+5. **When to Use**: Always define clear usage guidelines
+6. **Security**: Review before enabling
+7. **Testing**: Test skills in isolation
+
+## Standard Categories
+
+- `api` - API integrations
+- `automation` - Task automation
+- `communication` - Messaging, email
+- `data` - Data processing
+- `development` - Coding, Git, dev tools
+- `media` - Images, audio, video
+- `productivity` - Task management
+- `system` - System administration
+- `web` - Web scraping, browsing
+
+## Contributing
+
+1. Create skill in `skills/`
+2. Follow format guidelines
+3. Run security scan
+4. Test thoroughly
+5. Submit PR
+
+## Resources
+
+- [agentskills.io](https://agentskills.io) - Specification
+- `skills/example-skill/` - Template
+- `src/skills/` - Implementation