Cross-Platform Skills System for CodingBuddy

[JeremyDev87]

Cross-Platform Skills System for CodingBuddy

Summary

Add a shared skills system to .ai-rules/ that works across all supported AI tools (Claude Code, Codex, Cursor, Antigravity, Q, Kiro).

Background

Current State

CodingBuddy provides:

• Rules: Workflow guidelines (core.md, project.md, augmented-coding.md)
• Agents: Specialist profiles (12 JSON files)
• Adapters: Tool-specific integration guides

Missing: Reusable skills - structured workflows that can be invoked on-demand across AI tools.

Why This Matters

User Benefits

• Consistency: Same skills work identically across Claude Code, Codex, Cursor
• Reusability: Common workflows (TDD, debugging, code review) defined once
• Discoverability: Clear skill catalog with descriptions

Technical Benefits

• Superpowers Compatibility: Same SKILL.md format enables ecosystem interop
• MCP Integration: Skills accessible via MCP tools for programmatic access
• Adapter Pattern: Each AI tool uses its native capabilities

Reference Implementation

Superpowers plugin structure:

skills/
├── brainstorming/SKILL.md
├── test-driven-development/SKILL.md
└── systematic-debugging/SKILL.md

SKILL.md format:

---
name: skill-name
description: "When to use this skill"
---

# Skill Title

## Content...

---

Scope

In Scope

1. Skills Directory Structure

   • packages/rules/.ai-rules/skills/
   • SKILL.md format with YAML frontmatter

2. Core Skills (Initial Set)

   • tdd - Test-Driven Development workflow
   • debugging - Systematic debugging process
   • code-review - Code review checklist
   • planning - Implementation planning

3. MCP Tool Integration

   • list_skills - List available skills
   • get_skill - Get skill content by name

4. Adapter Updates

   • Claude Code: Skill tool mapping
   • Codex: Shell script wrapper
   • Cursor: Rules injection guide

Out of Scope

• Custom skill creation UI
• Skill versioning system
• Skill dependencies/chaining
• Runtime skill validation

---

Acceptance Criteria

Phase 1: Skills Infrastructure

• Create skills/ directory structure
• Define SKILL.md format specification
• Create skill schema validation (Zod)
• Add list_skills MCP tool
• Add get_skill MCP tool

Phase 2: Core Skills

• Create tdd/SKILL.md
• Create debugging/SKILL.md
• Create code-review/SKILL.md
• Create planning/SKILL.md

Phase 3: Adapter Integration

• Update adapters/claude-code.md with skill usage
• Update adapters/codex.md with shell wrapper
• Update adapters/cursor.md with rules injection
• Update other adapters as needed

Phase 4: Documentation

• Create skills/README.md with catalog
• Add skill creation guide
• Update main documentation

---

Affected Files

packages/rules/.ai-rules/
├── skills/                        # NEW
│   ├── README.md                  # Skill catalog and guide
│   ├── tdd/SKILL.md              # TDD workflow
│   ├── debugging/SKILL.md        # Debugging process
│   ├── code-review/SKILL.md      # Code review checklist
│   └── planning/SKILL.md         # Planning workflow
├── adapters/
│   ├── claude-code.md            # UPDATE: Skill mapping
│   ├── codex.md                  # UPDATE: Shell wrapper
│   └── cursor.md                 # UPDATE: Rules injection
└── rules/
    └── (unchanged)

apps/mcp-server/src/
├── mcp/
│   ├── mcp-serverless.ts         # UPDATE: Add skill tools
│   └── mcp.service.ts            # UPDATE: Add skill tools
├── rules/
│   ├── rules.service.ts          # UPDATE: Skill loading
│   ├── rules.types.ts            # UPDATE: Skill types
│   └── skill.schema.ts           # NEW: Zod schema
└── shared/
    └── (unchanged)

---

Technical Design

Skill Schema

// skill.schema.ts
import * as z from 'zod';

export const SkillFrontmatterSchema = z.object({
  name: z.string().min(1).regex(/^[a-z0-9-]+$/),
  description: z.string().min(1).max(500),
});

export interface Skill {
  name: string;
  description: string;
  content: string;
  path: string;
}

MCP Tools

// list_skills tool
{
  name: "list_skills",
  description: "List all available skills with descriptions",
  inputSchema: {},
  output: {
    skills: [
      { name: "tdd", description: "..." },
      { name: "debugging", description: "..." }
    ]
  }
}

// get_skill tool
{
  name: "get_skill",
  description: "Get skill content by name",
  inputSchema: {
    skillName: z.string()
  },
  output: {
    name: "tdd",
    description: "...",
    content: "# TDD Workflow\n\n..."
  }
}

Adapter Patterns

Claude Code (Native Skill tool):

Skills are accessible via the `Skill` tool:
- `Skill("codingbuddy:tdd")` - TDD workflow
- `Skill("codingbuddy:debugging")` - Debugging process

Codex (Shell wrapper):

# ~/.codex/bin/codingbuddy-skill
#!/bin/bash
cat ~/.codex/codingbuddy/skills/$1/SKILL.md

Cursor (Rules injection):

To use a skill, include its content in your prompt:
@skills/tdd/SKILL.md

---

Risk Assessment

Risk	Impact	Likelihood	Mitigation
Format incompatibility	Medium	Low	Follow Superpowers format exactly
MCP tool complexity	Low	Low	Simple file reading only
Adapter maintenance	Medium	Medium	Clear documentation

---

Success Metrics

• All 4 core skills created and validated
• MCP tools working in serverless and stdio modes
• At least 3 adapters updated with skill usage
• Documentation complete with examples