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:

---
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:

---
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:

// .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):

# 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:

# 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

---
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:

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
• Anthropic Skills Repository
• OpenCode Documentation
• Model Context Protocol Specification

---

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