Skip to main content

OSSA Skills Extension Implementation

OSSA Skills Extension Implementation

Overview

The Skills Extension enables Claude Desktop and Cursor to discover and invoke OSSA agents as callable skills using slash commands (e.g., /devops:mr-review).

Changes

1. OSSA Manifest Schema Extension

Added new skills extension to OSSA v0.3.3 manifests:

extensions:
  skills:
    enabled: true
    skill_name: "category:name"        # e.g., devops:mr-review
    description: "One-sentence description"
    invocation: "When to use this skill"
    instructions: |
      Detailed instructions including:
      - What the skill does
      - Usage examples
      - Expected output format

2. Updated Agent Manifests

Completed (3 agents):

  1. code-reviewer (packages/@ossa/code-reviewer/agent.ossa.yaml)

    • Skill: dev:analyze-project
    • Purpose: Deep code analysis and quality assessment

  2. security-scanner (packages/@ossa/security-scanner/agent.ossa.yaml)

    • Skill: devops:security-scan
    • Purpose: Security vulnerability scanning

  3. ci-fixer-worker (packages/@ossa/ci-fixer-worker/agent.ossa.yaml)

    • Skill: devops:ci-debug
    • Purpose: Debug and fix failing CI/CD pipelines

Note: mr-reviewer was archived/consolidated in release/v0.1.x

3. Agent-BuildKit Integration

Created new buildkit skills command for managing skills:

Commands:

  • buildkit skills list - List all skills
  • buildkit skills get <manifestPath> - Get skill details
  • buildkit skills validate [--manifest <path>] - Validate skills
  • buildkit skills generate <manifestPath> - Generate skills config
  • buildkit skills export --format <claude-desktop|cursor|both> - Export to JSON
  • buildkit skills add <manifestPath> - Add skills extension interactively

Files Added:

  • src/types/skills.types.ts - TypeScript types and Zod schemas
  • src/services/skills.service.ts - Skills CRUD service
  • src/cli/commands/skills.command.ts - CLI commands
  • test-skills.ts - Test script

Skills Extension Schema

Field Definitions

{
  enabled: boolean;                    // Enable/disable skill
  skill_name: string;                  // Format: "category:name"
  description: string;                 // 10-200 chars, user-facing
  invocation: string;                  // When to use (10-300 chars)
  instructions: string;                // Detailed guide (50+ chars)
}

Validation Rules

  1. skill_name: Must match regex /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/

    • Valid: devops:mr-review, cs:expansion, dev:analyze-project
    • Invalid: MrReview, mr_review, mr-review (no category)

  2. description: 10-200 characters, clear and concise

  3. invocation: Describes triggers/use cases

  4. instructions: Should include:

    • Usage: section with input format
    • Output: section with expected results
    • Examples when helpful

Export Formats

Claude Desktop (skills.json)

{
  "skills": [
    {
      "name": "devops:mr-review",
      "description": "Perform comprehensive code review on a GitLab merge request",
      "invocation": "Use when reviewing GitLab merge requests",
      "manifest": "/path/to/agent.ossa.yaml",
      "instructions": "..."
    }
  ]
}

Cursor (cursor-skills.json)

{
  "version": "0.4.9",
  "skills": [
    {
      "id": "devops-mr-review",
      "name": "mr-reviewer",
      "description": "...",
      "trigger": "/devops:mr-review",
      "manifestPath": "/path/to/agent.ossa.yaml",
      "category": "devops"
    }
  ]
}

Skill Categories

Recommended categories:

  • devops: CI/CD, deployment, operations (mr-review, ci-debug, deploy)
  • dev: Development tools (analyze-project, refactor, tdd-setup)
  • cs: Customer Success (expansion, qbr, health-check, onboarding)
  • gitlab: GitLab-specific (dashboard, duo-analyze, glql)
  • api: API tooling (sync-apidog, validate-api)

Implementation Status

Phase 1: Core Implementation ✓

  • Skills Extension schema design
  • TypeScript types and Zod validation
  • Skills service (CRUD operations)
  • CLI commands
  • 3 production agents updated

Phase 2: Rollout (In Progress)

  • code-reviewer
  • security-scanner
  • ci-fixer-worker (devops:ci-debug)
  • mr-reviewer (archived in release/v0.1.x)
  • cluster-operator (devops:k8s-ops)
  • documentation-aggregator (dev:doc-gen)
  • drupal-standards-checker (dev:drupal-standards)
  • issue-lifecycle-manager (gitlab:issue-triage)
  • kagent-worker (devops:kagent-ops)
  • mcp-server-builder (dev:mcp-builder)
  • module-generator (dev:module-gen)
  • ossa-validator (dev:ossa-validate)
  • pipeline-remediation (devops:pipeline-fix)
  • release-coordinator (devops:release-coord)
  • token-optimizer (dev:token-optimize)
  • vulnerability-scanner (devops:vuln-scan)
  • wiki-aggregator (dev:wiki-aggregate)

Phase 3: Testing & Documentation

  • Generate comprehensive skills.json for all agents
  • Test with Claude Desktop
  • Test with Cursor
  • Update agent platform docs

Usage Examples

For Users (Claude Desktop/Cursor)

User: /devops:mr-review https://gitlab.com/blueflyio/platform-agents/-/merge_requests/845

Agent: I'll review MR #845 for you. Let me analyze:
- Code quality and style
- Security vulnerabilities
- Test coverage
- CI pipeline status
...

For Developers

# List all skills
buildkit skills list --path ./platform-agents/packages/@ossa

# Validate a skill
buildkit skills validate --manifest ./mr-reviewer/agent.ossa.yaml

# Export all skills
buildkit skills export --format both --path ./packages/@ossa --output ./dist

# Add skill to manifest
buildkit skills add ./new-agent/agent.ossa.yaml \
  --skill-name "devops:new-skill" \
  --description "Does something awesome" \
  --invocation "Use when doing awesome things" \
  --instructions "Detailed instructions here..."

Testing

Manual Validation

  1. Check YAML syntax:

    yamllint packages/@ossa/*/agent.ossa.yaml

  2. Verify skill_name format:

    grep -r "skill_name:" packages/@ossa/ | grep -v "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"

  3. Check required fields:

    grep -A 5 "skills:" packages/@ossa/*/agent.ossa.yaml

Automated Testing (once buildkit builds)

npm --prefix agent-buildkit test
npm --prefix agent-buildkit run build
buildkit skills validate --path ./platform-agents/packages/@ossa
buildkit skills export --format both --output ./test-export

Migration Guide

To add skills extension to existing OSSA manifest:

  1. Determine category:name

    • Use existing categories when possible
    • Follow kebab-case convention

  2. Add extension block

    extensions:
  skills:
    enabled: true
    skill_name: "category:name"
    description: "Clear, concise description"
    invocation: "When to invoke"
    instructions: |
      **Usage:**
      - Input format
      - Parameters

      **Output:**
      - What to expect

  3. Validate

    buildkit skills validate --manifest path/to/agent.ossa.yaml

References

Next Steps

  1. Complete Phase 2 rollout (remaining 15 agents)
  2. Generate production skills.json files
  3. Test with Claude Desktop and Cursor
  4. Create MRs for review
  5. Update platform documentation
  6. Announce to team

Questions?

Contact: thomas@bluefly.io GitLab: @thomasscola