@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/docs/skills.md

@@ -0,0 +1,405 @@
+# PoolBot Skills System
+
+The PoolBot Skills System provides modular, discoverable capabilities defined in SKILL.md files. Skills follow the [agentskills.io](https://agentskills.io) specification and support progressive disclosure, security scanning, and context integration.
+
+## Overview
+
+Skills are self-contained capability modules that:
+
+- **Define when to use** them with clear criteria
+- **Provide practical examples** and templates
+- **Support progressive loading** (metadata → summary → full content)
+- **Are automatically security scanned** for common vulnerabilities
+- **Can be enabled/disabled** per session or globally
+- **Integrate with the context engine** for LLM prompt injection
+
+## Quick Start
+
+### Listing Skills
+
+```bash
+# List all skills
+poolbot skills list
+
+# Filter by category
+poolbot skills list --category=productivity
+
+# Show only enabled/disabled
+poolbot skills list --enabled
+poolbot skills list --disabled
+```
+
+### Viewing Skills
+
+```bash
+# View skill details (full content)
+poolbot skills view github
+
+# View with specific disclosure level
+poolbot skills view github --level=summary
+poolbot skills view github --level=metadata
+```
+
+### Searching Skills
+
+```bash
+# Search by text
+poolbot skills search git
+
+# Search with filters
+poolbot skills search deploy --tag=devops
+```
+
+### Managing Skills
+
+```bash
+# Enable/disable skills
+poolbot skills enable github
+poolbot skills disable github
+
+# Security scan
+poolbot skills scan
+poolbot skills scan ./skills/my-skill
+
+# Statistics
+poolbot skills 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 and
+  when to use it.
+version: 1.0.0             # Semver version
+author: Your Name          # Author attribution
+categories:                # Classification
+  - productivity
+  - automation
+tags:                      # Searchable tags
+  - git
+  - github
+  - devops
+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
+
+## Common Commands
+
+```bash
+# Example command
+poolbot command --option
+```
+
+## Templates
+
+```bash
+# Reusable template
+echo "Template content"
+```
+```
+
+### Frontmatter Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique kebab-case identifier |
+| `name` | string | Yes | Human-readable name |
+| `description` | string | Yes | What the skill does |
+| `version` | string | Yes | Semver version |
+| `author` | string | No | Author attribution |
+| `categories` | string[] | No | Classification tags |
+| `tags` | string[] | No | Searchable keywords |
+| `metadata.poolbot.emoji` | string | No | Emoji icon |
+| `metadata.poolbot.always` | boolean | No | Load on every session |
+| `metadata.poolbot.requires.bins` | string[] | No | Required binaries |
+| `metadata.poolbot.requires.env` | string[] | No | Required env vars |
+| `metadata.poolbot.install` | array | No | Auto-install specs |
+
+### Categories
+
+Choose from these standard categories:
+
+- `communication` - Messaging, email, notifications
+- `productivity` - Task management, notes, calendar
+- `development` - Coding, git, CI/CD
+- `devops` - Infrastructure, deployment, monitoring
+- `data` - Databases, analytics, processing
+- `media` - Images, video, audio
+- `automation` - Workflows, scripting
+- `integration` - APIs, webhooks, services
+- `utility` - General-purpose tools
+
+## Security
+
+All skills are automatically scanned for:
+
+- **Prompt injection** - Attempts to override system instructions
+- **Command injection** - Dangerous shell command patterns
+- **Path traversal** - File system escape attempts
+- **Hardcoded credentials** - Passwords, tokens, keys
+- **Suspicious encoding** - Base64 obfuscation
+- **Data exfiltration** - Unauthorized data transmission
+
+### Security Levels
+
+| Severity | Description | Action |
+|----------|-------------|--------|
+| Critical | Immediate security risk | Block loading |
+| High | Significant risk | Warn user |
+| Medium | Moderate concern | Log only |
+| Low | Minor issue | Silent |
+| Info | FYI | Silent |
+
+### Strict Mode
+
+Enable strict mode to block skills with any high/critical findings:
+
+```typescript
+import { initSkills } from "./skills/index.js";
+
+await initSkills({
+  security: {
+    strictMode: true,  // Block on high/critical findings
+    autoScan: true,    // Scan on load
+  },
+});
+```
+
+## Context Integration
+
+Skills can be automatically injected into LLM prompts based on the conversation context.
+
+### Progressive Disclosure
+
+Content loads incrementally to manage token usage:
+
+1. **Metadata** (~50 tokens) - ID, name, description
+2. **Summary** (~200 tokens) - Metadata + first section
+3. **Full** (all tokens) - Complete content
+
+### Query-Based Loading
+
+```typescript
+import { loadSkillForQuery } from "./skills/index.js";
+
+// Load skills relevant to a query
+const skills = await loadSkillForQuery("deploy to production", {
+  maxTokens: 2000,
+  disclosure: "summary",
+});
+```
+
+### Context Preparation
+
+```typescript
+import { prepareSkillsForContext } from "./skills/index.js";
+
+// Prepare skills for LLM context
+const context = await prepareSkillsForContext({
+  skillIds: ["github", "docker"],
+  maxTokens: 4000,
+  disclosure: "full",
+});
+```
+
+## Programmatic API
+
+### Registry
+
+```typescript
+import { getRegistry } from "./skills/index.js";
+
+const registry = getRegistry();
+
+// Add a skill
+await registry.addSkill("/path/to/skill");
+
+// Search
+const results = registry.searchSkills({
+  query: "git",
+  category: "development",
+});
+
+// Enable/disable
+registry.enableSkill("github");
+registry.disableSkill("github");
+
+// Listen for events
+registry.on("skillLoaded", (skill) => {
+  console.log(`Loaded: ${skill.name}`);
+});
+```
+
+### Parser
+
+```typescript
+import { parseSkillFile } from "./skills/index.js";
+
+const skill = parseSkillFile("/path/to/SKILL.md");
+console.log(skill.metadata.name);
+```
+
+### Security
+
+```typescript
+import { scanSkill, quickSecurityCheck } from "./skills/index.js";
+
+// Full scan
+const report = scanSkill("my-skill", skillContent);
+console.log(report.findings);
+
+// Quick check
+const isSafe = quickSecurityCheck("my-skill", skillContent);
+```
+
+## Examples
+
+See the `skills/example-skill/SKILL.md` file for a comprehensive template.
+
+### Simple Skill
+
+```markdown
+---
+id: hello
+name: Hello World
+description: A simple greeting skill
+version: 1.0.0
+categories: [utility]
+tags: [demo, example]
+---
+
+# Hello World
+
+Says hello to the user.
+
+## When to Use
+
+Use when you want to greet someone.
+
+## Commands
+
+```bash
+echo "Hello, World!"
+```
+```
+
+### Complex Skill
+
+```markdown
+---
+id: kubernetes-deploy
+name: Kubernetes Deployment
+description: Deploy applications to Kubernetes clusters
+version: 2.1.0
+author: DevOps Team
+categories: [devops, automation]
+tags: [k8s, kubernetes, deploy, helm]
+metadata:
+  poolbot:
+    emoji: ☸️
+    requires:
+      bins: [kubectl, helm]
+      env: [KUBECONFIG]
+---
+
+# Kubernetes Deployment
+
+Deploy and manage applications on Kubernetes clusters.
+
+## When to Use
+
+✅ **USE when:**
+- Deploying to Kubernetes
+- Managing Helm releases
+- Checking pod status
+
+❌ **DON'T use when:**
+- Working with Docker Compose
+- Managing bare-metal servers
+
+## Common Commands
+
+```bash
+# Apply manifests
+kubectl apply -f deployment.yaml
+
+# Check status
+kubectl get pods -n production
+
+# Deploy with Helm
+helm upgrade --install myapp ./chart
+```
+```
+
+## Best Practices
+
+1. **Clear descriptions** - Make the purpose obvious
+2. **Specific criteria** - Define when to use (and when not to)
+3. **Practical examples** - Include real, tested commands
+4. **Security first** - Never include credentials
+5. **Version properly** - Use semantic versioning
+6. **Categorize well** - Choose appropriate categories
+7. **Tag thoroughly** - Include relevant keywords
+8. **Test examples** - Ensure commands actually work
+
+## Troubleshooting
+
+### Skill not appearing
+
+- Check file is named exactly `SKILL.md`
+- Verify YAML frontmatter is valid
+- Ensure file is in a subdirectory of `skills/`
+
+### Security scan failures
+
+- Review findings with `poolbot skills scan`
+- Remove hardcoded credentials
+- Avoid suspicious patterns
+- Use environment variables for secrets
+
+### Context not loading
+
+- Check skill is enabled: `poolbot skills list --enabled`
+- Verify token limits aren't exceeded
+- Try lower disclosure level
+
+## See Also
+
+- [agentskills.io specification](https://agentskills.io)
+- [Example Skill](../skills/example-skill/SKILL.md)
+- [CLI Reference](./cli/skills.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolzin/pool-bot",
-  "version": "2026.3.6",
+  "version": "2026.3.9",
   "description": "🎱 Pool Bot - AI assistant with PLCODE integrations",
   "keywords": [],
   "license": "MIT",

package/skills/example-skill/SKILL.md

@@ -0,0 +1,195 @@
+---
+id: example-skill
+name: Example Skill
+description: |
+  A comprehensive example demonstrating the SKILL.md format for PoolBot.
+  Use this as a template when creating new skills.
+version: 1.0.0
+author: PoolBot Team
+categories:
+  - examples
+  - documentation
+tags:
+  - template
+  - reference
+  - tutorial
+metadata:
+  poolbot:
+    emoji: 📚
+    always: false
+    requires:
+      bins: []
+      env: []
+    install: []
+---
+
+# Example Skill
+
+This is a comprehensive example of a SKILL.md file that demonstrates all the features of the PoolBot skills system.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- You want to learn about the SKILL.md format
+- You need a template for creating new skills
+- You're exploring PoolBot's capabilities
+
+❌ **DON'T use this skill when:**
+
+- You need to perform actual work (this is just documentation)
+- You're looking for production-ready automation
+
+## Overview
+
+Skills in PoolBot are modular capabilities defined in SKILL.md files. They follow the agentskills.io specification and 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 skills`
+
+## File Structure
+
+```
+skills/
+└── my-skill/
+    └── SKILL.md          # Main skill definition
+```
+
+## Frontmatter Format
+
+The frontmatter (YAML between `---` markers) contains metadata:
+
+```yaml
+---
+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]
+---
+```
+
+## Content Sections
+
+### When to Use
+
+Clearly define when this skill should and shouldn't be used. This helps the LLM make better decisions.
+
+### Common Commands
+
+Include practical examples:
+
+```bash
+# Example command
+poolbot skills list
+
+# Example with options
+poolbot skills search --category=examples
+```
+
+### Templates
+
+Provide reusable templates:
+
+```bash
+# Template for skill creation
+mkdir skills/my-skill
+cat > skills/my-skill/SKILL.md << 'EOF'
+---
+id: my-skill
+name: My Skill
+description: Description here
+version: 1.0.0
+---
+
+# My Skill
+
+Content here...
+EOF
+```
+
+## Best Practices
+
+1. **Clear descriptions**: Make it obvious what the skill does
+2. **Specific use cases**: Define when to use (and when NOT to use)
+3. **Practical examples**: Include real commands users can run
+4. **Security awareness**: Don't include hardcoded credentials
+5. **Versioning**: Use semantic versioning
+6. **Categories**: Choose appropriate categories for discoverability
+
+## Security Considerations
+
+Skills are automatically scanned for:
+
+- **Prompt injection** attempts
+- **Command injection** patterns
+- **Path traversal** attacks
+- **Hardcoded credentials**
+- **Suspicious encoding**
+- **Data exfiltration** endpoints
+
+Always review skills before enabling them, especially if they:
+- Execute shell commands
+- Access sensitive data
+- Make network requests
+
+## CLI Commands
+
+```bash
+# List all skills
+poolbot skills list
+
+# Search skills
+poolbot skills search github
+
+# View skill details
+poolbot skills view github
+
+# Enable/disable skills
+poolbot skills enable my-skill
+poolbot skills disable my-skill
+
+# Security scan
+poolbot skills scan
+
+# Statistics
+poolbot skills stats
+```
+
+## Linked Files
+
+You can reference additional files that will be loaded with the skill:
+
+```markdown
+See also: [Advanced Usage](./advanced.md)
+Related: [API Reference](./api.md)
+```
+
+## Notes
+
+- Skills are loaded from `skills/` directory
+- Subdirectories are scanned recursively
+- Files must be named `SKILL.md` (case-sensitive)
+- Frontmatter is required
+- Content supports full Markdown