skills/RFC-AI-AGENT-EXTENSIBILITY-PATTERNS.md

# RFC: AI Agent Extensibility Patterns

**Status:** Draft  
**Author:** Dan (with Claude Code assistance)  
**Date:** 2025-11-09  
**Version:** 0.1.0

## Abstract

This RFC defines the standard patterns for extending AI coding agents (Claude Code, OpenCode, Cursor, etc.) across our organization. It establishes when to use Skills, Commands, Tools, and MCP servers, with examples from our current implementations.

## Motivation

As we build AI-assisted workflows, we need clear guidelines on:
- When to use which extension mechanism
- How to maintain consistency across repos
- How to share capabilities between agents
- How to balance simplicity with power

**Current state:** Ad-hoc decisions leading to inconsistent patterns.  
**Desired state:** Clear, documented standards that make the right choice obvious.

---

## Extension Mechanisms

### 1. Skills (SKILL.md format)

**What:** Markdown files with YAML frontmatter containing detailed instructions for multi-step workflows.

**When to use:**
- ✅ Multi-step processes (5+ steps)
- ✅ Workflows requiring domain knowledge
- ✅ Processes with bundled resources (scripts, templates, docs)
- ✅ Tasks that benefit from progressive disclosure
- ✅ Cross-agent compatibility is desired

**When NOT to use:**
- ❌ Simple one-off commands
- ❌ Programmatic operations needing code execution
- ❌ Real-time data fetching

**Structure:**
```
skill-name/
├── SKILL.md           # Required: Instructions with YAML frontmatter
├── scripts/           # Optional: Helper scripts
├── references/        # Optional: Supporting documentation
└── assets/            # Optional: Templates, configs
```

**Example frontmatter:**
```yaml
---
name: worklog
description: Create comprehensive structured org-mode worklogs documenting work sessions in docs/worklogs/. Use when the user explicitly asks to document work, create/write a worklog, log the session, or record what was accomplished.
---
```

**Current implementations:**
- `worklog` - Creates structured org-mode documentation
- `niri-window-capture` - Invisibly captures window screenshots

**Requested from skills team:**
- `update-opencode` - Updates OpenCode version via Nix (see Examples section)

**Deployment:**
- **Claude Code:** Native support via `.claude/skills/`
- **OpenCode:** Via `opencode-skills` plugin (1.0.44 compatible)
- **Universal:** Via `openskills` CLI tool for all agents

### 2. Slash Commands

**What:** Short markdown files that trigger predefined prompts/workflows.

**When to use:**
- ✅ Quick shortcuts (1-3 steps)
- ✅ Common repeated tasks
- ✅ Simple prompt templates
- ✅ OpenCode-specific workflows

**When NOT to use:**
- ❌ Complex multi-step processes (use Skills)
- ❌ Need bundled resources (use Skills)
- ❌ Cross-agent compatibility required

**Structure:**
```markdown
---
description: Run tests with coverage and suggest fixes
agent: build
---

Run the full test suite with coverage report and show any failures.

!`nix flake check 2>&1 || true`

Focus on the failing tests and suggest fixes. If tests pass, provide a brief summary.
```

**Location:** `.opencode/command/*.md`

**Current implementations:**
- `/test` - Runs test suite with coverage
- `/rebuild` - Rebuilds NixOS configuration

**Deployment:**
- **OpenCode:** Native support
- **Other agents:** Not supported (use Skills instead)

### 3. Custom Tools (Plugin API)

**What:** TypeScript/JavaScript code that extends agent capabilities programmatically.

**When to use:**
- ✅ Programmatic operations (parsing, transformation)
- ✅ Need to maintain state
- ✅ Complex logic that's hard to express as instructions
- ✅ Agent-specific integrations

**When NOT to use:**
- ❌ Simple workflows (use Skills/Commands)
- ❌ Static instructions (use Skills)
- ❌ Cross-agent compatibility required

**Structure:**
```typescript
// .opencode/tool/my-tool.ts
import { tool } from "@opencode-ai/plugin";

export default tool({
  name: "my_tool",
  description: "What this tool does",
  parameters: z.object({
    param: z.string(),
  }),
  execute: async ({ param }) => {
    // Implementation
    return result;
  },
});
```

**Current implementations:**
- None yet in our org

**Deployment:**
- **OpenCode:** Native plugin API
- **Other agents:** Not portable

### 4. MCP Servers (Model Context Protocol)

**What:** External services that provide dynamic data/tools via standardized protocol.

**When to use:**
- ✅ Database connections
- ✅ External API integrations
- ✅ Real-time data fetching
- ✅ Service-to-agent communication
- ✅ Need authentication/secrets management

**When NOT to use:**
- ❌ Static workflows (use Skills)
- ❌ Simple prompts (use Commands)
- ❌ Don't need external services

**Current implementations:**
- None yet in our org

**Deployment:**
- **Claude Code:** Native MCP support
- **OpenCode:** Emerging MCP support
- **Other agents:** Varies

---

## Decision Framework

Use this flowchart to decide which pattern to use:

```
Is it a workflow with instructions?
├─ Yes: Is it complex (5+ steps) or needs bundled resources?
│  ├─ Yes: Use SKILL.md
│  └─ No: Is it OpenCode-specific?
│     ├─ Yes: Use slash command
│     └─ No: Use SKILL.md for portability
│
└─ No: Does it need programmatic logic?
   ├─ Yes: Does it need external services/data?
   │  ├─ Yes: Use MCP Server
   │  └─ No: Use Custom Tool (if agent-specific) or bash script
   │
   └─ No: Reconsider if it should be a Skill
```

**Examples:**

| Task | Pattern | Reason |
|------|---------|--------|
| Update OpenCode version | Skill | Multi-step workflow, can bundle helper scripts |
| Run tests | Command | Quick shortcut, OpenCode-specific |
| Create worklog | Skill | Complex workflow, bundled templates |
| Capture window | Skill | Multi-step, bundled scripts, cross-agent |
| Parse config file | Tool | Programmatic logic |
| Fetch live data | MCP | External service, real-time |

---

## Implementation Guidelines

### Skills

**Naming:**
- Lowercase with hyphens: `update-opencode`, `worklog`, `niri-window-capture`
- Directory name must match frontmatter `name` field

**Description requirements:**
- Minimum 20 characters (for LLM discoverability)
- Include when to use: "Use when user asks to X"
- Be specific about capabilities

**Instructions format:**
- Use imperative mood ("Read the file", not "You should read")
- Number multi-step processes
- Reference bundled resources with relative paths
- Include base directory context for agent

**Progressive disclosure:**
- Keep descriptions concise (for `<available_skills>` list)
- Put detailed instructions in SKILL.md body
- Only load full content when skill is invoked

### Commands

**Keep them simple:**
- 1-3 steps maximum
- Use `!` for bash command execution
- Specify agent type in frontmatter if specialized

### Deployment Strategy

**For dotfiles repo (NixOS system):**
```nix
# home/opencode.nix or home/claude.nix
home.file.".config/opencode/skills/skill-name" = {
  source = ../claude/skills/skill-name;
  recursive = true;
};
```

**For project repos:**
- Commit to `.claude/skills/` or `.opencode/skills/`
- Reference in AGENTS.md for universal agents
- Use `openskills` for cross-agent compatibility

**For shared/org-wide skills:**
- Maintain in `~/proj/skills` repo
- Deploy via Nix modules or git submodules
- Document in DEPLOYED.md

---

## Security Considerations

**Skills can execute arbitrary code** via bash commands and bundled scripts:

1. **Review all scripts** in `scripts/` before deployment
2. **Document security implications** in SECURITY.md (see `niri-window-capture`)
3. **Log security-sensitive operations** (e.g., to systemd journal)
4. **Use principle of least privilege** in bundled scripts
5. **Never commit secrets** in skill files

**For security-sensitive skills:**
```markdown
# skill-name/SECURITY.md

⚠️ **SECURITY NOTICE**: This skill can [describe capability].

## Threat Model
- [What can go wrong]
- [Who might exploit it]

## Mitigations
- [How we limit risk]
- [Logging/auditing]

## Deployment Considerations
- [Production vs development]
```

---

## Maintenance & Versioning

**Skills should include:**
- Version in directory structure: `skill-name-v1/`
- Changelog in README.md
- Dependencies in frontmatter (if needed)

**When updating:**
1. Test in development environment
2. Update version documentation
3. Commit with clear description of changes
4. Deploy via Nix rebuild or skill manager

**Deprecation:**
1. Mark as deprecated in description
2. Keep for 30 days minimum
3. Create migration guide if replacement exists
4. Remove after deprecation period

---

## Examples from Our Org

### Worklog Skill (Complex Workflow)

**Pattern:** Skill  
**Reason:** Multi-step documentation process with templates

```markdown
---
name: worklog
description: Create comprehensive structured org-mode worklogs documenting work sessions in docs/worklogs/. Use when the user explicitly asks to document work, create/write a worklog, log the session, or record what was accomplished.
---

# Worklog Skill

## When to Use
- "Document today's work"
- "Create a worklog"
- "Record this session"

## Context Gathering
1. Check git status: `git status`
2. Get recent commits: `git log --oneline -10`
3. Review uncommitted changes: `git diff --stat`

## Document Creation
[Detailed steps using templates/...]
```

### Niri Window Capture (Tool + Workflow)

**Pattern:** Skill with bundled scripts  
**Reason:** Complex setup, security considerations, reusable scripts

```
niri-window-capture/
├── SKILL.md              # Instructions
├── SECURITY.md           # Threat model and mitigations
├── scripts/
│   ├── capture-focused.sh
│   ├── capture-by-title.sh
│   └── capture-all-windows.sh
└── examples/
    └── usage-example.sh
```

### Update OpenCode (Requested from Skills Team)

**Pattern:** Skill  
**Reason:** Multi-step Nix workflow, could bundle helper scripts  
**Status:** 🔴 Needs implementation by skills team

**Use Case:** Operations team needs to check for and apply OpenCode updates without manually editing Nix files and fetching SHA256 hashes.

**Proposed structure:**
```
update-opencode/
├── SKILL.md              # Instructions for checking/updating
├── scripts/
│   ├── check-version.sh  # Compare current vs latest
│   └── fetch-sha256.sh   # Get SHA256 for new version
└── references/
    └── nix-package-format.md  # Example Nix package structure
```

**Key requirements:**
1. Check current OpenCode version from `pkgs/opencode/default.nix`
2. Query GitHub API for latest release
3. If newer version available:
   - Fetch SHA256 hash for new release
   - Update version and hash in Nix file
   - Trigger system rebuild
   - Verify successful update
4. Handle errors gracefully (network issues, invalid releases, etc.)

**Expected workflow:**
```markdown
User: "Update OpenCode to the latest version"
Agent: [Invokes skills_update_opencode]
        1. Current: 1.0.44
        2. Latest: 1.0.51
        3. Fetching SHA256...
        4. Updating pkgs/opencode/default.nix
        5. Rebuilding system...
        6. ✓ Updated to 1.0.51
```

**Related:**
- Dotfiles repo: `/home/dan/proj/dotfiles/pkgs/opencode/default.nix`
- Current manual process documented in dotfiles repo
- Should work with pinned versions (currently pinned to 1.0.44 for plugin compatibility)

---

## Migration Path

### Phase 1: Document Current State (This RFC)
- ✅ Identify existing patterns
- ✅ Document decision framework
- ✅ Establish guidelines

### Phase 2: Standardize Existing Skills
- Audit current skills for compliance
- Add missing SECURITY.md where needed
- Standardize naming and structure

### Phase 3: Tooling & Automation
- Create skill template generator
- Add linting for skill structure
- Automate deployment testing

### Phase 4: Expand
- Build out shared skill library
- Create org-wide skill registry
- Document best practices from experience

---

## Open Questions

1. **Skill versioning:** Should we version skills or use git tags?
2. **Testing:** How do we test skills before deployment?
3. **Discovery:** How do users find available skills across repos?
4. **Conflicts:** What happens when multiple repos define same skill name?
5. **Performance:** Impact of many skills on agent context/startup time?

---

## References

- [Anthropic Agent Skills Specification](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Anthropic Skills Repository](https://github.com/anthropics/skills)
- [OpenCode Documentation](https://opencode.ai/docs)
- [Model Context Protocol Specification](https://modelcontextprotocol.io)

---

## Appendix: Current Tool Inventory

### Dotfiles Repo
- **Skills:**
  - `worklog` - Structured documentation creation
  - `niri-window-capture` - Window screenshot capture
- **Commands:**
  - `/test` - Run test suite
  - `/rebuild` - System rebuild
- **Plugins:**
  - `opencode-skills@0.1.0` - Skill loader (OpenCode 1.0.44 compatible)

### Skills Repo
- **Requested Skills (for team to implement):**
  - `update-opencode` - Check and apply OpenCode updates in dotfiles Nix setup
- **In Development:**
  - Various project-specific skills

---

## Approval Process

**Review Period:** 1 week  
**Feedback Channel:** GitHub issues or comments in this file  
**Final Approval:** Team consensus

**Reviewers:**
- [ ] Technical lead
- [ ] Operations team
- [ ] Development team

---

## Changelog

- **2025-11-09:** Initial draft based on dotfiles experience and research