skills/docs/emes-conversion-guide.md

emes Plugin Conversion Guide

Converting skills to emes-style plugin architecture for portability.

Background

The emes org builds modular AI agent tools:

• tissue: Git-native issue tracking (machine-first)
• idle: Quality gate (blocks exit until reviewer approves)
• jwz: Async messaging with identity/git context
• marketplace: Plugin distribution registry

Key Principles

1. Pull context on-demand - Don't inject large prompts upfront
2. Mechanical enforcement - Use hooks, not prompt instructions
3. References over inline - Point to files, don't embed content
4. Machine-first interfaces - JSON output, non-interactive

Directory Structure

Before (current):

skills/my-skill/
├── SKILL.md           # Instructions with YAML frontmatter
├── README.md          # Human docs
└── scripts/           # Supporting scripts (optional)

After (emes-style):

skills/my-skill/
├── .claude-plugin/
│   └── plugin.json    # Metadata, version, hooks
├── skills/
│   └── my-skill.md    # Auto-discovered skill (copy of SKILL.md)
├── hooks/
│   └── hooks.json     # Optional lifecycle hooks
├── SKILL.md           # Keep for Nix deployment (backward compat)
├── README.md
└── scripts/

plugin.json Schema

{
  "name": "my-skill",
  "description": "Brief description",
  "version": "1.0.0",
  "author": {
    "name": "author-name"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "hooks": {
    "SessionStart": [...],
    "PostToolUse": [...]
  }
}

Conversion Checklist

• Create .claude-plugin/plugin.json with metadata
• Copy SKILL.md to skills/<name>.md
• Add hooks if skill needs lifecycle events
• Keep original SKILL.md for Nix deployment
• Test with /plugin install ./path/to/skill
• Register in marketplace.json (optional)

Hook Events

Available hook events:

• SessionStart - On session begin
• SessionEnd - On session end
• PreToolUse - Before tool execution
• PostToolUse - After tool execution
• PreCompact - Before context compaction
• UserPromptSubmit - On user message
• Stop - When agent stops
• SubagentStop - When subagent stops
• Notification - On notifications

Example: Quality Gate (idle pattern)

For skills that need review before completion:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "check-review-status.sh"
          }
        ]
      }
    ]
  }
}

Testing

# Install locally
/plugin install ./skills/my-skill

# Or add to marketplace and install
/plugin marketplace add owner/repo
/plugin install my-skill@marketplace-name

Dual Deployment

We maintain both:

1. Nix deployment (system-level) - Uses SKILL.md at root
2. Plugin discovery (Claude Code) - Uses skills/<name>.md

This allows skills to work in both environments.