ronitchidara 5aae2aa197 security: comprehensive pre-PR security audit fixes (rebased)

2026-01-28 17:03:07 +05:30

11 KiB

Raw Blame History

title	description
Contributing Skills	How to create, test, and publish Moltbot skills

Contributing Skills

This guide walks you through creating skills for Moltbot, from your first SKILL.md to publishing on ClawdHub.

What is a Skill?

A skill is a directory containing a SKILL.md file that teaches Moltbot how to use a tool, service, or workflow. Skills are injected into the system prompt and guide the AI agent on how to accomplish specific tasks.

Skills follow the AgentSkills specification with Moltbot-specific extensions.

Quick Start

Create your first skill in under 5 minutes:

# Create skill directory
mkdir -p ~/.clawdbot/skills/my-calculator

# Create SKILL.md
cat > ~/.clawdbot/skills/my-calculator/SKILL.md << 'EOF'
---
name: my-calculator
description: Perform calculations using bc (basic calculator)
metadata: {"clawdbot":{"requires":{"bins":["bc"]}}}
---

# Calculator

Use `bc` for arithmetic calculations.

## Examples

Simple math:
```bash
echo "2 + 2" | bc

With decimals (scale=2):

echo "scale=2; 10 / 3" | bc

Notes

Always use echo "expression" | bc pattern
Set scale=N for decimal precision EOF


Start a new Moltbot session and the skill will be available.

## SKILL.md Format

### Required Fields

Every `SKILL.md` must have YAML frontmatter with at least:

```yaml
---
name: skill-name
description: One-line description of what this skill does
---

Full Frontmatter Reference

---
name: my-skill                    # Unique identifier (kebab-case)
description: Short description    # Shown in skill lists
homepage: https://example.com     # Link to tool/service docs
user-invocable: true              # Expose as /my-skill command (default: true)
disable-model-invocation: false   # Exclude from AI prompt (default: false)
command-dispatch: tool            # Optional: bypass AI, call tool directly
command-tool: exec                # Tool to invoke when command-dispatch is set
command-arg-mode: raw             # How to pass args (default: raw)
metadata: {"clawdbot":{...}}      # Moltbot-specific configuration (see below)
---

Metadata Object

The metadata field must be a single-line JSON object (parser limitation):

metadata: {"clawdbot":{"emoji":"🔧","requires":{"bins":["jq"]},"primaryEnv":"MY_API_KEY"}}

Metadata Fields

Field	Type	Description
`emoji`	string	Display emoji for UI
`homepage`	string	URL for documentation link
`always`	boolean	Skip all gating, always load
`os`	string[]	Platform filter: `["darwin"]`, `["linux"]`, `["win32"]`
`requires.bins`	string[]	All binaries must exist on PATH
`requires.anyBins`	string[]	At least one binary must exist
`requires.env`	string[]	Environment variables (or config equivalents)
`requires.config`	string[]	Config paths that must be truthy
`primaryEnv`	string	Main env var for `skills.entries.<name>.apiKey`
`install`	object[]	Installation instructions for UI
`skillKey`	string	Override config key (default: skill name)

Gating Requirements

Skills are filtered at load time based on metadata.clawdbot.requires:

# Require specific binaries
metadata: {"clawdbot":{"requires":{"bins":["gh","jq"]}}}

# Require at least one of these binaries
metadata: {"clawdbot":{"requires":{"anyBins":["vim","nvim"]}}}

# Require environment variable (or config equivalent)
metadata: {"clawdbot":{"requires":{"env":["GITHUB_TOKEN"]}}}

# Require config value to be set
metadata: {"clawdbot":{"requires":{"config":["browser.enabled"]}}}

# Platform-specific (macOS only)
metadata: {"clawdbot":{"os":["darwin"]}}

# Combine requirements
metadata: {"clawdbot":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"]},"os":["darwin","linux"]}}

Install Specs

Help users install dependencies via the macOS Skills UI:

# Homebrew
metadata: {"clawdbot":{"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"}]}}

# npm (global)
metadata: {"clawdbot":{"install":[{"id":"npm","kind":"node","package":"my-cli","bins":["my-cli"],"label":"Install my-cli (npm)"}]}}

# Go
metadata: {"clawdbot":{"install":[{"id":"go","kind":"go","package":"github.com/user/tool@latest","bins":["tool"],"label":"Install tool (go)"}]}}

# uv (Python)
metadata: {"clawdbot":{"install":[{"id":"uv","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}

# Download (tarball/zip)
metadata: {"clawdbot":{"install":[{"id":"download","kind":"download","url":"https://example.com/tool.tar.gz","archive":"tar.gz","bins":["tool"],"label":"Download tool"}]}}

# Platform-specific
metadata: {"clawdbot":{"install":[{"id":"brew-mac","kind":"brew","formula":"tool","bins":["tool"],"os":["darwin"]},{"id":"apt-linux","kind":"download","url":"https://example.com/tool-linux","os":["linux"]}]}}

Writing Good Instructions

The body of SKILL.md (after frontmatter) is injected into the system prompt. Write clear, actionable instructions.

Do

Use code blocks with specific commands
Include common use cases and examples
Document required environment variables
Explain output formats the agent should expect
Use {baseDir} to reference the skill directory

Don't

Write lengthy explanations (tokens cost money)
Include installation instructions (use install metadata)
Duplicate information already in tool --help
Add promotional content

Example Structure

# Tool Name

Brief description of what this tool does.

## Commands

Primary command:
```bash
tool command --flag "argument"

With options:

tool command --verbose --output json

Environment

TOOL_API_KEY: Required API key
TOOL_REGION: Optional region (default: us-east-1)

Notes

Important behavior to know
Common gotchas


### Using {baseDir}

Reference files within your skill directory:

```markdown
Run the bundled script:
```bash
uv run {baseDir}/scripts/generate.py --prompt "hello"


Moltbot replaces `{baseDir}` with the actual skill path at runtime.

## Supporting Files

Skills can include additional files:

my-skill/ ├── SKILL.md # Required ├── scripts/ # Helper scripts │ └── generate.py ├── templates/ # Template files │ └── config.yaml └── examples/ # Example usage └── demo.sh


Reference these with `{baseDir}`:

```markdown
Use the template:
```bash
cp {baseDir}/templates/config.yaml ./my-config.yaml


## Testing Your Skill

### Local Testing

1. Create the skill in `~/.clawdbot/skills/` or `<workspace>/skills/`
2. Verify it loads: `clawdbot skills list`
3. Check gating: `clawdbot skills info <name>`
4. Start a session and test the skill

### Checking Eligibility

```bash
# List all skills with status
clawdbot skills list

# Detailed skill info
clawdbot skills info my-skill

# Check why a skill isn't loading
clawdbot doctor

Token Impact

Skills add to your prompt token count. Estimate:

Base overhead: ~50 tokens (when any skills load)
Per skill: ~25 tokens + your instruction length

Keep instructions concise. Every character counts.

Configuration

Users can configure your skill in ~/.clawdbot/clawdbot.json:

{
  skills: {
    entries: {
      "my-skill": {
        enabled: true,
        apiKey: "sk-xxx",           // Maps to primaryEnv
        env: {
          MY_API_KEY: "sk-xxx",     // Additional env vars
          MY_REGION: "us-east-1"
        },
        config: {
          endpoint: "https://api.example.com"  // Custom config
        }
      }
    }
  }
}

Access custom config via environment or document the config path for users.

Publishing to ClawdHub

Prerequisites

Install the ClawdHub CLI: npm i -g clawdhub
Log in: clawdhub login

First Publish

# Navigate to your skill
cd ~/.clawdbot/skills/my-skill

# Publish
clawdhub publish . \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "Initial release"

Updating

# Bump version and publish
clawdhub publish . \
  --slug my-skill \
  --version 1.1.0 \
  --changelog "Added new feature"

Sync Workflow

For managing multiple skills:

# Scan and publish all new/updated skills
clawdhub sync --all

# Preview what would be published
clawdhub sync --dry-run

# Specify version bump type
clawdhub sync --all --bump minor

Versioning

ClawdHub uses semantic versioning:

Patch (1.0.1): Bug fixes, documentation updates
Minor (1.1.0): New features, backward compatible
Major (2.0.0): Breaking changes to usage or requirements

Best Practices

Naming

Use kebab-case: my-skill-name
Be descriptive but concise
Avoid generic names: prefer github-pr-review over github

Dependencies

Prefer tools available via Homebrew, npm, or Go
Document all required binaries in requires.bins
Provide install specs for the macOS UI
Test on a clean system

Security

Never hardcode secrets in SKILL.md
Use requires.env for API keys
Document environment variables clearly
Consider sandbox compatibility

Documentation

Write for the AI agent, not humans
Use imperative commands: "Run...", "Use...", "Execute..."
Include example output when helpful
Keep instructions under 1KB when possible

Example Skills

Browse the bundled skills for patterns:

Skill	Description	Key Patterns
nano-banana-pro	Image generation	Python script, uv, API key
github	GitHub operations	gh CLI, OAuth
peekaboo	macOS screenshots	Platform-specific, node binary
gemini	Gemini CLI	Homebrew install

Troubleshooting

Skill not loading

Check clawdbot skills list for status
Run clawdbot doctor for diagnostics
Verify binary requirements: which <binary>
Check env vars: echo $MY_VAR
Validate SKILL.md syntax (single-line metadata JSON)

Gating issues

# Debug skill eligibility
clawdbot skills info my-skill --verbose

Publish errors

Ensure you're logged in: clawdhub whoami
Check slug uniqueness on clawdhub.com
Verify SKILL.md is valid YAML frontmatter

Resources

Skills reference - Full configuration docs
ClawdHub guide - Registry CLI reference
Sandboxing - Running skills in containers
Feature maturity - Skills system stability
clawdhub.com - Browse existing skills

11 KiB Raw Blame History

Contributing Skills

What is a Skill?

Quick Start

Notes

Full Frontmatter Reference

Metadata Object

Metadata Fields

Gating Requirements

Install Specs

Writing Good Instructions

Do

Don't

Example Structure

Environment

Notes

Token Impact

Configuration

Publishing to ClawdHub

Prerequisites

First Publish

Updating

Sync Workflow

Versioning

Best Practices

Naming

Dependencies

Security

Documentation

Example Skills

Troubleshooting

Skill not loading

Gating issues

Publish errors

Resources

11 KiB

Raw Blame History