Problem (Critical Bug)

The osiris-component-developer skill was teaching incorrect capabilities format that would cause validation failures.

What Was Wrong ❌

# Skill taught THIS (incorrect):
capabilities:
  - discover
  - healthcheck    # doesn't exist!
  - bulkOperations

Issues:

1. Capabilities as array instead of object
2. Referenced non-existent "healthcheck" capability
3. Components following skill would fail validation

What's Correct ✅

According to components/spec.schema.json:

# Must be object with boolean flags:
capabilities:
  discover: true            # Supports schema/metadata discovery
  adHocAnalytics: false     # Supports ad-hoc analytical queries
  inMemoryMove: false       # Supports in-memory data movement
  streaming: false          # Supports streaming/incremental processing
  bulkOperations: true      # Supports bulk insert/update operations
  transactions: false       # Supports transactional operations
  partitioning: false       # Supports partitioned processing
  customTransforms: false   # Supports custom transformation logic

8 standard capabilities (per spec.schema.json):

• discover, adHocAnalytics, inMemoryMove, streaming
• bulkOperations, transactions, partitioning, customTransforms

Note: No "healthcheck" or "doctor" capability exists. doctor() is a driver method, not a capability.

Changes

Fixed in 4 files:

1. SKILL.md:

   • Fixed spec.yaml template with correct object format
   • Updated frontmatter description
   • Fixed docstrings for discover() and doctor() methods

2. CHECKLIST.md:

   • Updated CAP-001: "Declares capabilities object (not array)"
   • Updated CAP-002: "Sets discover: true if mode includes discover"
   • Updated CAP-003: Lists all 8 standard capabilities
   • Updated CAP-004: Clarifies only true capabilities need implementation

3. POSTHOG_EXAMPLE.md:

   • Fixed example spec.yaml to use object format
   • Added all 8 standard capabilities with comments

4. TEMPLATES.md:

   • Fixed minimal spec.yaml template with correct format

Validation

✅ Checked against actual component specs:

• components/mysql.extractor/spec.yaml
• components/supabase.extractor/spec.yaml
• components/filesystem.csv_extractor/spec.yaml

✅ Confirmed against components/spec.schema.json

✅ Reference docs (docs/reference/COMPONENT_CAPABILITIES_*.md) already correct

Credit

Issue discovered by Codex CLI review. Thanks to OpenAI model for catching this critical bug! 🙏

Impact

• Before: Following skill would create invalid specs → validation failure
• After: Skill teaches correct format → components validate successfully

🤖 Generated with Claude Code