Custom tools like skills.

[victorhdchagas]

Custom Tools like Skills

Summary

I propose adding a Custom Tools system to Picoclaw, similar to the existing Skills system, that allows users to install and use external tools from GitHub repositories without recompiling Picoclaw.

Background

Currently, Picoclaw has two extensibility mechanisms:

Built-in Tools (System Resources)

These are compiled Go binaries (pkg/tools/*.go) that provide core functionality:

• read_file, write_file, list_dir - File system operations
• exec - Shell command execution
• web_search, web_fetch - Web operations
• cron - Task scheduling
• message, spawn - Communication features

Characteristics:

• Implemented in Go, compiled into the binary
• Registered at runtime in AgentLoop
• Execute deterministically with validated parameters
• Low token overhead (only description in context)

Skills

These are markdown-based packages that extend agent capabilities:

• Located in skills/*/SKILL.md
• Contain instructions, workflows, domain knowledge
• May include scripts, references, assets
• Loaded into context when triggered

Characteristics:

• Markdown files with YAML frontmatter
• Contain procedural knowledge and workflows
• Can bundle scripts in scripts/ directory
• Load entire content into context when triggered (~5k tokens)
• Best for: complex workflows, domain expertise, documentation

Problem Statement

Skills + Scripts work, but have limitations:

1. Context Bloat: SKILL.md files (up to 5k tokens) are loaded entirely into LLM context even when just using a simple script
2. No Discovery: LLM needs to read SKILL.md to discover available scripts/functions
3. Manual Configuration: Configuration is text-based, requires manual file editing
4. Unstructured Parameters: No schema definition, LLM must guess script syntax
5. No Type Safety: Parameters are plain text, no validation
6. Difficult to Reuse: Each skill redefines similar patterns

Proposed Solution: Custom Tools

Custom Tools are script-based tools that can be installed from GitHub, similar to how Skills are installed, but with benefits of Built-in Tools (structured, low-overhead, discoverable).

Architecture

custom-tool/
├── TOOL.md              # Metadata + schema
├── script.py           # Implementation (Python/Bash/Node)
└── requirements.txt     # Dependencies (optional)

TOOL.md Structure

---
name: github_updates
description: "Check latest updates from GitHub repositories"
executor: python3
script: script.py
timeout: 30
configs:
  - name: token
    type: string
    required: true
    secret: true
    description: "GitHub personal access token"
parameters:
  - name: repo
    type: string
    required: true
    description: "Repository in format owner/repo"
---

# GitHub Updates Tool

Checks for latest commits, PRs, and issues from GitHub repositories.

Configuration Management

Custom Tools support structured configuration (no environment variables):

{
  "tools": {
    "web": { ... },
    "custom": {
      "github_updates": {
        "token": "ghp_xxxxxxxxxxxx"
      },
      "db_query": {
        "host": "localhost",
        "port": 5432,
        "user": "postgres",
        "password": "secret"
      }
    }
  }
}

Features:

• Interactive configuration wizard: picoclaw custom-tools configure <tool-name>
• Local config files: ~/.picoclaw/workspace/custom-tools/<name>/config.json.local
• Secret masking: values marked secret: true never shown in logs
• Default values from TOOL.md

CLI Commands

# List installed custom tools
picoclaw custom-tools list

# Install from GitHub
picoclaw custom-tools install victorhdchagas/github-updates

# Configure a tool
picoclaw custom-tools configure db_query

# Show configuration (secrets masked)
picoclaw custom-tools show-config db_query

# Remove a tool
picoclaw custom-tools remove github-updates

Comparison Table

Aspect	Built-in Tools	Skills	Skills + Scripts	Custom Tools
Implementation	Go (compiled)	Markdown	Markdown + Scripts	Markdown + Scripts
Context Overhead	~100 tokens	~5k tokens	~5k tokens	~100 tokens
Discovery	Automatic	Manual (read SKILL.md)	Manual (read SKILL.md)	Automatic
Parameters	Structured schema	N/A	Text instructions	Structured schema
Type Safety	Yes	N/A	No	Yes
Configuration	Code/JSON	Manual	Manual	Interactive
Execution	Direct	Via exec tool	Via exec tool	Direct execution
Install	Recompile required	picoclaw skills install	picoclaw skills install	picoclaw custom-tools install
Best For	Core system ops	Workflows, domain knowledge	Reusable scripts	External APIs, data fetching

Use Cases

Example 1: GitHub Updates

Before (Skills):

User: "Check updates for sipeed/picoclaw"
  ↓
LLM loads SKILL.md (5k tokens)
  ↓
LLM reads instructions: "Use scripts/updates.py with --token"
  ↓
LLM reads config file manually
  ↓
LLM constructs: exec("path/to/updates.py --token TOKEN --repo REPO")
  ↓
Result returned

After (Custom Tools):

User: "Check updates for sipeed/picoclaw"
  ↓
LLM sees tool: github_updates(repo)
  ↓
LLM calls: github_updates(repo="sipeed/picoclaw")
  ↓
Tool executes script, returns data
  ↓
LLM interprets and responds

Example 2: Database Query

TOOL.md:

---
name: db_query
description: "Execute queries on PostgreSQL databases"
executor: python3
script: query.py
timeout: 60
configs:
  - name: host
    type: string
    required: true
  - name: password
    type: string
    required: true
    secret: true
parameters:
  - name: query
    type: string
    required: true
---

Usage:

User: "How many users signed up today?"
  ↓
LLM calls: db_query(query="SELECT COUNT(*) FROM users WHERE date = TODAY()")
  ↓
Tool loads config (host, password from config.json)
  ↓
Tool executes script
  ↓
Result returned

Benefits

1. Low Token Overhead: Only description (~100 tokens) in context, not full SKILL.md
2. Automatic Discovery: LLM sees all custom tools in available tools list
3. Structured Parameters: Schema defined in TOOL.md, validated at runtime
4. Type Safety: Parameter types enforced
5. Easy Configuration: Interactive wizard, no manual file editing
6. Secure by Default: Secret masking, automatic validation
7. No Recompilation: Install tools at runtime from GitHub
8. Community Sharing: Easy to create and share custom tools

Implementation Estimate

• New files: ~5
• Modified files: ~4
• Lines of code: ~1,300
• Development time: 8-12 hours
• Complexity: Medium

Open Questions

1. Script Languages: Support Python, Bash, and Node.js? Or add more (Rust, Go)?
2. Configuration Storage: Centralize in config.json or allow per-tool local configs?
3. Validation: Should installation fail if dependencies are missing?
4. Repository: Create picoclaw-custom-tools repository for community tools?
5. Backward Compatibility: Keep existing skills system as-is?

Next Steps

If this proposal is well-received, implementation would involve:

1. Create pkg/tools/custom.go with ExternalTool struct
2. Create pkg/tools/custom_installer.go for installation from GitHub
3. Create pkg/tools/custom_loader.go for loading custom tools
4. Create pkg/tools/custom_config.go for configuration management
5. Add CLI commands in cmd/picoclaw/custom_tools.go
6. Integrate with existing AgentLoop and ToolRegistry

Looking forward to feedback and suggestions from the community!

---

Related:

• Skills system: picoclaw/skills/
• Built-in tools: pkg/tools/
• Tool installer pattern: pkg/skills/installer.go (similar pattern)

[victorhdchagas]

This could be useful, because i could configure a pg_tool, and speak with my database. Or Obsidian Tool, and speak with my diary.
Each custom tool could have instructions to usage ..
I can handle this, but i don't know if this is useful to project owners.