Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (58 loc) · 3.86 KB

CONTRIBUTING.md

File metadata and controls

86 lines (58 loc) · 3.86 KB

Contributing

There are three ways to contribute to NanoClaw.

1. Source Code Changes

Accepted: Bug fixes, security fixes, simplifications, reducing code.

Not accepted: Features, capabilities, compatibility, enhancements. These should be plugins or skills.

2. Skill Plugins

A skill plugin adds an integration (calendar, weather, search, home automation, etc.) that agents can use inside their containers. Skills are installed per-deployment — the plugins/ directory is gitignored so each user's installation is different.

Skills live in the nanotars-skills marketplace. The main repo contains only core skills (nanotars-*) and creation tools (create-*-plugin).

How to contribute a skill plugin:

  1. Run /create-skill-plugin — it scaffolds everything: plugin.json, hook files, container skills, and an installation skill
  2. Test it locally with the generated /add-skill-{name} command
  3. Publish to the marketplace with /nanotars-publish-skill {name}

3. Channel Plugins

A channel plugin connects NanoClaw to a messaging platform (Telegram, Slack, SMS, etc.). Channel plugins implement the Channel interface defined in src/plugin-types.ts.

How to contribute a channel plugin:

  1. Run /create-channel-plugin — it scaffolds the channel implementation and an installation skill
  2. Test it locally with the generated /add-channel-{name} command
  3. Publish to the marketplace with /nanotars-publish-skill {name}

Plugin Structure

At runtime, every plugin lives in plugins/ and has a plugin.json manifest. In the repo, the plugin template lives in .claude/skills/add-{type}-{name}/files/ and gets copied to plugins/ when the installation skill runs.

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "containerEnvVars": ["MY_API_KEY"],
  "hooks": ["onStartup", "onShutdown"],
  "containerHooks": ["hooks/post-tool-use.js"],
  "channelPlugin": false,
  "dependencies": true
}

Key concepts:

  • containerEnvVars — env var names from .env to inject into agent containers
  • hooks — host-side lifecycle hooks (onStartup, onShutdown, onInboundMessage, onChannel)
  • containerHooks — SDK hooks that run inside agent containers
  • channelPlugin — true for channel plugins that provide messaging I/O
  • dependencies — true if the plugin has its own package.json/node_modules
  • Dockerfile.partial — extra build steps merged into the agent container image

For complete documentation, run /create-skill-plugin or /create-channel-plugin.

Why Skills Over Features?

Every user should have clean, minimal code that does exactly what they need. Skills let users selectively add capabilities to their fork without inheriting code for features they don't want. The base repository stays small and understandable.

Testing

Test your contribution by running it on a fresh clone before submitting. For plugins, verify:

  • The installation skill runs to completion
  • The plugin loads without errors (plugin-loader.ts discovers it)
  • No hardcoded secrets (use containerEnvVars in plugin.json)

Maintaining Bundled Container Skills

A few skills under container/skills/ (currently agent-browser, welcome, self-customize) are derived from upstream qwibitai/nanoclaw v2 and adapted for v1's capability surface. To check for upstream improvements:

# Diff each bundled skill against v2's current version (no changes applied)
bash scripts/sync-container-skills-from-v2.sh

# Apply updates from v2 (review the diff first; v1-specific adaptations
# may need to be re-applied to new content)
bash scripts/sync-container-skills-from-v2.sh --apply

# Just one skill at a time
bash scripts/sync-container-skills-from-v2.sh --skill self-customize

If you have a local v2 checkout, set V2_PATH=/path/to/nanoclaw-v2 to skip the clone.