Get the FREE Ultimate OpenClaw Setup Guide →

Pynchy Plugin Authoring

Scanned
npx machina-cli add skill crypdick/pynchy/pynchy-plugin-authoring --openclaw
Files (1)
SKILL.md
3.7 KB

Pynchy Plugin Authoring

When To Use

Use this skill when the user asks to:

  • Create a new pynchy plugin
  • Add a new hook to an existing plugin
  • Register/enable plugins in config.toml
  • Validate plugin discovery and runtime behavior

Core Rules

  1. Keep plugin responsibilities narrow. One plugin can implement multiple hooks, but avoid unrelated concerns in one package.
  2. In the plugin repository pyproject.toml (not pynchy/pyproject.toml), define entry points under [project.entry-points."pynchy"].
  3. For host runtime/channel code, treat plugin code as high trust and avoid risky side effects in import-time code.
  4. For plugin docs, cross-link to pynchy/docs/plugins/* instead of duplicating long explanations.
  5. Refer to the quickstart guide for the recommended plugin directory structure.
  6. Plugin config models belong in the plugin. Define Pydantic config models inside the plugin's own source file, not in pynchy/src/pynchy/config/models.py. The core config/models.py is for pynchy core settings only.

File Scope Conventions

When this skill mentions config files, use this mapping:

  • Host app config: config.toml ([plugins.<name>] entries enable repos)
  • Host app package metadata: pyproject.toml
  • Plugin package metadata: <plugin-repo>/pyproject.toml (entry points live here)
  • Plugin source: <plugin-repo>/src/<plugin_module>/...

Authoring Workflow

Copy this checklist and complete it in order:

Plugin Authoring Checklist
- [ ] Choose plugin scope and hook categories
- [ ] Create plugin directory structure (or update existing plugin)
- [ ] Implement hook methods and runtime logic
- [ ] Add/update tests
- [ ] Configure local pynchy [plugins.<name>] entry
- [ ] Run tests and smoke checks
- [ ] Update docs if behavior is user-visible

Hook Map

  • pynchy_create_channel: Host-side channel instance
  • pynchy_service_handler: Host-side service tool handlers (IPC dispatch)
  • pynchy_skill_paths: Skill directories mounted into container
  • pynchy_agent_core_info: Agent core implementation metadata
  • pynchy_container_runtime: Host container runtime provider
  • pynchy_workspace_spec: Managed workspace/task definitions (e.g., periodic agents)

Hook reference:

  • docs/plugins/hooks.md

Config-Managed Plugin Registration

For local pynchy, prefer config-managed plugin repos:

[plugins.example]
repo = "owner/pynchy-plugin-example"
ref = "main"
enabled = true

Then restart pynchy. Startup sync handles clone/update and host install.

If the host is remote, don't forget to ssh into it and add the plugin to the config.toml file.

Validation Commands

For plugin repositories:

uv run pytest

For pynchy docs link safety after docs changes:

uv run mkdocs build --strict

Security

All plugin Python code runs on the host during discovery (__init__, validate(), category methods). Installing a plugin means trusting its code. Only install plugins from authors you trust.

For the full risk-by-category breakdown, see Plugin Security.

References

  • Plugin overview: docs/plugins/index.md
  • Plugin quickstart (creation guide): docs/plugins/quickstart.md
  • Hook reference: docs/plugins/hooks.md
  • Packaging guidance: docs/plugins/packaging.md
  • Available plugin registry: docs/plugins/available.md

Source

git clone https://github.com/crypdick/pynchy/blob/main/.claude/skills/pynchy-plugin-authoring/SKILL.mdView on GitHub

Overview

Pynchy Plugin Authoring guides you through creating, scaffolding, or updating pynchy plugins across channels, MCP servers, skills, agent cores, workspace specs, and container runtimes. It also covers registering plugins via config.toml, adding entry points, and validating plugin hook wiring and discovery. Following these guidelines keeps plugins cohesive, secure, and correctly wired to host runtimes.

How This Skill Works

This skill outlines a practical plugin workflow: structure the plugin with a clear directory layout, declare entry points in the plugin's pyproject.toml under [project.entry-points."pynchy"], and configure host loading via config.toml. Host code treats plugin loading as high-trust during discovery and import, so avoid risky side effects in import-time code. Validation uses tests (pytest) and docs checks to ensure correct hook wiring and runtime behavior.

When to Use It

  • Create a new pynchy plugin
  • Add a new hook to an existing plugin
  • Register/enable plugins in config.toml
  • Validate plugin discovery and runtime behavior
  • Update or scaffold existing plugin components (channels, MCP servers, skills, agent cores, workspace specs, and container runtime plugins)

Quick Start

  1. Step 1: Plan the plugin scope and hook categories for the new or updated plugin
  2. Step 2: Create/update the plugin directory, implement hooks, and declare entry points in the plugin's pyproject.toml
  3. Step 3: Configure the host via config.toml, run pytest and mkdocs builds, and document any user-visible changes

Best Practices

  • Keep plugin scope narrow and cohesive; one plugin should implement a related set of hooks
  • Define entry points in the plugin's pyproject.toml under [project.entry-points."pynchy"]
  • Treat plugin code as high-trust during host discovery and avoid import-time side effects
  • Place plugin config models inside the plugin source, not in pynchy core config
  • Cross-link docs and follow the quickstart plugin structure in the repo

Example Use Cases

  • Create a new pynchy plugin for a custom channel and its pynchy_create_channel hook
  • Add a new hook to an existing plugin and wire it to pynchy_service_handler
  • Register and enable a plugin via config.toml on the host app
  • Validate plugin discovery and runtime behavior with pytest and smoke checks
  • Update plugin docs and cross-link to docs/plugins/* after changes

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗