@poolzin/pool-bot 2026.3.7 → 2026.3.10

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/extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/bluebubbles",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot BlueBubbles channel plugin",
   "poolbot": {

package/extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/copilot-proxy",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot Copilot Proxy provider plugin",
   "poolbot": {

package/extensions/diagnostics-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/diagnostics-otel",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot diagnostics OpenTelemetry exporter",
   "poolbot": {

package/extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/discord",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot Discord channel plugin",
   "poolbot": {

package/extensions/feishu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolzin/feishu",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "description": "Pool Bot Feishu/Lark channel plugin (community maintained by @m1heng)",
   "type": "module",
   "dependencies": {

package/extensions/google-antigravity-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/google-antigravity-auth",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot Google Antigravity OAuth provider plugin",
   "poolbot": {

package/extensions/google-gemini-cli-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/google-gemini-cli-auth",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot Gemini CLI OAuth provider plugin",
   "poolbot": {

package/extensions/googlechat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolbot/googlechat",
-  "version": "2026.3.4",
+  "version": "2026.3.10",
   "type": "module",
   "description": "Poolbot Google Chat channel plugin",
   "poolbot": {

package/extensions/hexstrike-bridge/README.md

@@ -0,0 +1,119 @@
+# HexStrike Bridge Extension
+
+Integração do PoolBot com HexStrike AI - plataforma de segurança com 150+ scanners.
+
+## Visão Geral
+
+Esta extensão conecta o PoolBot ao HexStrike AI, permitindo executar scans de segurança diretamente via CLI e gateway.
+
+## Funcionalidades
+
+- **150+ ferramentas de segurança** disponíveis via HexStrike
+- **Scans assíncronos** com acompanhamento de progresso
+- **CLI integrada** - comandos `poolbot security`
+- **Gateway RPC** - métodos para integração com outros sistemas
+
+## Instalação
+
+A extensão é carregada automaticamente pelo PoolBot quando presente no diretório `extensions/`.
+
+## Configuração
+
+```json
+{
+  "hexstrike-bridge": {
+    "baseUrl": "http://localhost:8888",
+    "timeoutMs": 300000,
+    "maxConcurrentScans": 3
+  }
+}
+```
+
+| Opção | Descrição | Padrão |
+|-------|-----------|--------|
+| `baseUrl` | URL da API HexStrike | `http://localhost:8888` |
+| `timeoutMs` | Timeout de scans em ms | `300000` (5min) |
+| `maxConcurrentScans` | Máximo de scans paralelos | `3` |
+
+## Comandos CLI
+
+### Verificar status
+```bash
+poolbot security status
+```
+
+### Listar ferramentas disponíveis
+```bash
+poolbot security tools
+```
+
+### Executar scan
+```bash
+# Scan rápido (assíncrono)
+poolbot security scan nmap example.com
+
+# Scan com espera
+poolbot security scan nmap example.com --wait
+
+# Scan com timeout customizado
+poolbot security scan nmap example.com --wait --timeout 600
+```
+
+### Verificar status do scan
+```bash
+poolbot security scan-status <job-id>
+```
+
+## Gateway RPC Methods
+
+| Método | Descrição |
+|--------|-----------|
+| `security.status` | Status da conexão HexStrike |
+| `security.tools.list` | Lista ferramentas disponíveis |
+| `security.scan.start` | Inicia um novo scan |
+| `security.scan.status` | Status de um scan específico |
+| `security.scan.list` | Lista todos os scans ativos |
+
+## Exemplos de Uso
+
+### Scan de portas com Nmap
+```bash
+poolbot security scan nmap 192.168.1.1 --wait
+```
+
+### Scan de vulnerabilidades
+```bash
+poolbot security scan nikto https://example.com --wait
+```
+
+### Verificar todos os scans em andamento
+```bash
+poolbot security scan-list
+```
+
+## Requisitos
+
+- HexStrike AI rodando (por padrão em `localhost:8888`)
+- PoolBot v2026.3.9+
+
+## Troubleshooting
+
+### "HexStrike offline"
+Verifique se o HexStrike está rodando:
+```bash
+curl http://localhost:8888/health
+```
+
+### Timeout em scans longos
+Aumente o timeout na configuração:
+```json
+{
+  "hexstrike-bridge": {
+    "timeoutMs": 600000
+  }
+}
+```
+
+## Licença
+
+MIT - Parte do ecossistema PoolBot