gh-epieczko-betty/agents/meta.skill/README.md

meta.skill - Skill Creator Meta-Agent

Generates complete Betty skills from natural language descriptions.

Overview

meta.skill is a meta-agent that creates fully functional skills from simple description files. It generates skill definitions, Python implementations, tests, and documentation, following Betty Framework conventions.

What it does:

• Parses skill descriptions (Markdown or JSON)
• Generates skill.yaml configurations
• Creates Python implementation stubs
• Generates test templates
• Creates comprehensive README documentation
• Validates skill names and structure
• Registers artifact metadata

Quick Start

Create a Skill

# Create skill from description
python3 agents/meta.skill/meta_skill.py examples/my_skill_description.md

Output:

🛠️  meta.skill - Creating skill from examples/my_skill_description.md

✨ Skill 'data.transform' created successfully!

📄 Created files:
   - skills/data.transform/skill.yaml
   - skills/data.transform/data_transform.py
   - skills/data.transform/test_data_transform.py
   - skills/data.transform/README.md

✅ Skill 'data.transform' is ready to use
   Add to agent skills_available to use it.

Skill Description Format

Create a Markdown file with this structure:

# Name: domain.action

# Purpose:
Brief description of what the skill does

# Inputs:
- input_parameter_1
- input_parameter_2 (optional)

# Outputs:
- output_file_1.json
- output_file_2.yaml

# Permissions:
- filesystem:read
- filesystem:write

# Produces Artifacts:
- artifact-type-1
- artifact-type-2

# Consumes Artifacts:
- artifact-type-3

# Implementation Notes:
Detailed guidance for implementing the skill logic

Or use JSON format:

{
  "name": "domain.action",
  "purpose": "Brief description",
  "inputs": ["param1", "param2"],
  "outputs": ["output.json"],
  "permissions": ["filesystem:read"],
  "artifact_produces": ["artifact-type-1"],
  "artifact_consumes": ["artifact-type-2"],
  "implementation_notes": "Implementation guidance"
}

Generated Structure

For a skill named data.transform, meta.skill generates:

skills/data.transform/
├── skill.yaml                  # Skill configuration
├── data_transform.py           # Python implementation
├── test_data_transform.py      # Test suite
└── README.md                   # Documentation

skill.yaml

Complete skill configuration following Betty conventions:

name: data.transform
version: 0.1.0
description: Transform data between formats
inputs:
  - input_file
  - output_format
outputs:
  - transformed_data.json
status: active
permissions:
  - filesystem:read
  - filesystem:write
entrypoints:
  - command: /data/transform
    handler: data_transform.py
    runtime: python
    description: Transform data between formats
artifact_metadata:
  produces:
    - type: transformed-data
  consumes:
    - type: raw-data

Implementation Stub

Python implementation with:

• Proper imports and logging
• Class structure
• execute() method with typed parameters
• CLI entry point with argparse
• Error handling
• Output formatting (JSON/YAML)

#!/usr/bin/env python3
"""
data.transform - Transform data between formats

Generated by meta.skill
"""

import os
import sys
import json
import yaml
from pathlib import Path
from typing import Dict, List, Any, Optional

from betty.config import BASE_DIR
from betty.logging_utils import setup_logger

logger = setup_logger(__name__)


class DataTransform:
    """Transform data between formats"""

    def __init__(self, base_dir: str = BASE_DIR):
        """Initialize skill"""
        self.base_dir = Path(base_dir)

    def execute(self, input_file: Optional[str] = None,
                output_format: Optional[str] = None) -> Dict[str, Any]:
        """Execute the skill"""
        try:
            logger.info("Executing data.transform...")

            # TODO: Implement skill logic here
            # Implementation notes: [your notes here]

            result = {
                "ok": True,
                "status": "success",
                "message": "Skill executed successfully"
            }

            logger.info("Skill completed successfully")
            return result

        except Exception as e:
            logger.error(f"Error executing skill: {e}")
            return {
                "ok": False,
                "status": "failed",
                "error": str(e)
            }


def main():
    """CLI entry point"""
    import argparse

    parser = argparse.ArgumentParser(
        description="Transform data between formats"
    )

    parser.add_argument("--input-file", help="input_file")
    parser.add_argument("--output-format", help="output_format")
    parser.add_argument(
        "--output-format",
        choices=["json", "yaml"],
        default="json",
        help="Output format"
    )

    args = parser.parse_args()

    skill = DataTransform()
    result = skill.execute(
        input_file=args.input_file,
        output_format=args.output_format,
    )

    if args.output_format == "json":
        print(json.dumps(result, indent=2))
    else:
        print(yaml.dump(result, default_flow_style=False))

    sys.exit(0 if result.get("ok") else 1)


if __name__ == "__main__":
    main()

Test Template

pytest-based test suite:

#!/usr/bin/env python3
"""Tests for data.transform"""

import pytest
import sys
import os
from pathlib import Path

sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))

from skills.data_transform import data_transform


class TestDataTransform:
    """Tests for DataTransform"""

    def setup_method(self):
        """Setup test fixtures"""
        self.skill = data_transform.DataTransform()

    def test_initialization(self):
        """Test skill initializes correctly"""
        assert self.skill is not None
        assert self.skill.base_dir is not None

    def test_execute_basic(self):
        """Test basic execution"""
        result = self.skill.execute()
        assert result is not None
        assert "ok" in result
        assert "status" in result

    def test_execute_success(self):
        """Test successful execution"""
        result = self.skill.execute()
        assert result["ok"] is True
        assert result["status"] == "success"

    # TODO: Add more specific tests


def test_cli_help(capsys):
    """Test CLI help message"""
    sys.argv = ["data_transform.py", "--help"]

    with pytest.raises(SystemExit) as exc_info:
        data_transform.main()

    assert exc_info.value.code == 0

Skill Naming Convention

Skills must follow the domain.action format:

• domain: Category (e.g., data, api, file, text)
• action: Operation (e.g., validate, transform, parse)
• Use only lowercase letters and numbers (no hyphens, underscores, or special characters)

Valid examples:

• ✅ data.validate
• ✅ api.test
• ✅ file.compress
• ✅ text.summarize

Invalid examples:

• ❌ data.validate-json (hyphen not allowed)
• ❌ data_validate (underscore not allowed)
• ❌ DataValidate (uppercase not allowed)
• ❌ validate (missing domain)

Usage Examples

Example 1: JSON Validator

Description file (json_validator.md):

# Name: data.validatejson

# Purpose:
Validates JSON files against JSON Schema definitions

# Inputs:
- json_file_path
- schema_file_path (optional)

# Outputs:
- validation_result.json

# Permissions:
- filesystem:read

# Produces Artifacts:
- validation-report

# Implementation Notes:
Use Python's jsonschema library for validation

Create skill:

python3 agents/meta.skill/meta_skill.py json_validator.md

Example 2: API Tester

Description file (api_tester.json):

{
  "name": "api.test",
  "purpose": "Test API endpoints and generate reports",
  "inputs": ["openapi_spec_path", "base_url"],
  "outputs": ["test_results.json"],
  "permissions": ["network:http"],
  "artifact_produces": ["test-report"],
  "artifact_consumes": ["openapi-spec"],
  "implementation_notes": "Use requests library to test each endpoint"
}

Create skill:

python3 agents/meta.skill/meta_skill.py api_tester.json

Example 3: File Compressor

Description file (file_compressor.md):

# Name: file.compress

# Purpose:
Compress files using various algorithms

# Inputs:
- input_path
- compression_type (gzip, zip, tar.gz)

# Outputs:
- compressed_file

# Permissions:
- filesystem:read
- filesystem:write

# Implementation Notes:
Support gzip, zip, and tar.gz formats using Python standard library

Create skill:

python3 agents/meta.skill/meta_skill.py file_compressor.md

Integration

With meta.agent

Create an agent that uses the skill:

name: data.validator
description: Data validation agent
skills_available:
  - data.validatejson  # Skill created by meta.skill

With plugin.sync

Sync skills to plugin format:

python3 skills/plugin.sync/plugin_sync.py

This converts skill.yaml to commands in .claude-plugin/plugin.yaml.

Artifact Types

Consumes

• skill-description - Natural language skill requirements
  • Pattern: **/skill_description.md
  • Format: Markdown or JSON

Produces

• skill-definition - Complete skill configuration

  • Pattern: skills/*/skill.yaml
  • Schema: schemas/skill-definition.json

• skill-implementation - Python implementation code

  • Pattern: skills/*/[skill_module].py

• skill-tests - Test suite

  • Pattern: skills/*/test_[skill_module].py

• skill-documentation - README documentation

  • Pattern: skills/*/README.md

Common Workflows

Workflow 1: Create and Test Skill

# 1. Create skill description
cat > my_skill.md <<EOF
# Name: data.parse
# Purpose: Parse structured data from text
# Inputs:
- input_text
# Outputs:
- parsed_data.json
# Permissions:
- filesystem:write
EOF

# 2. Generate skill
python3 agents/meta.skill/meta_skill.py my_skill.md

# 3. Implement logic (edit the generated file)
vim skills/data.parse/data_parse.py

# 4. Run tests
pytest skills/data.parse/test_data_parse.py -v

# 5. Test CLI
python3 skills/data.parse/data_parse.py --help

Workflow 2: Create Skill for Agent

# 1. Create skill
python3 agents/meta.skill/meta_skill.py api_analyzer_skill.md

# 2. Add to agent
echo "  - api.analyze" >> agents/api.agent/agent.yaml

# 3. Sync to plugin
python3 skills/plugin.sync/plugin_sync.py

Workflow 3: Batch Create Skills

# Create multiple skills
for desc in skills_to_create/*.md; do
    echo "Creating skill from $desc..."
    python3 agents/meta.skill/meta_skill.py "$desc"
done

Tips & Best Practices

Skill Descriptions

Be specific about purpose:

# Good
# Purpose: Validate JSON against JSON Schema Draft 07

# Bad
# Purpose: Validate stuff

Include implementation notes:

# Implementation Notes:
Use the jsonschema library. Support Draft 07 schemas.
Provide detailed error messages with line numbers.

Specify optional parameters:

# Inputs:
- required_param
- optional_param (optional)
- another_optional (optional, defaults to 'value')

Parameter Naming

Parameters are automatically sanitized:

• Special characters removed (except -, _, spaces)
• Converted to lowercase
• Spaces and hyphens become underscores

Example conversions:

• "Schema File Path (optional)" → schema_file_path_optional
• "API-Key" → api_key
• "Input Data" → input_data

Implementation Strategy

1. Generate skeleton first - Let meta.skill create structure
2. Implement gradually - Add logic to execute() method
3. Test incrementally - Run tests after each change
4. Update documentation - Keep README current

Artifact Metadata

Always specify artifact types for interoperability:

# Produces Artifacts:
- openapi-spec
- validation-report

# Consumes Artifacts:
- api-requirements

This enables:

• Agent discovery via meta.compatibility
• Pipeline suggestions via meta.suggest
• Workflow orchestration

Troubleshooting

Invalid skill name

Error: Skill name must be in domain.action format: my-skill

Solution: Use format domain.action with only alphanumeric characters:

# Wrong: my-skill, my_skill, MySkill
# Right: data.transform, api.validate

Skill already exists

Error: Skill directory already exists: skills/data.validate

Solution: Remove existing skill or use different name:

rm -rf skills/data.validate

Import errors in generated code

ModuleNotFoundError: No module named 'betty.config'

Solution: Ensure Betty framework is in Python path:

export PYTHONPATH="${PYTHONPATH}:/home/user/betty"

Test failures

ModuleNotFoundError: No module named 'skills.data_validate'

Solution: Run tests from Betty root directory:

cd /home/user/betty
pytest skills/data.validate/test_data_validate.py -v

Architecture

meta.skill
    ├─ Input: skill-description (Markdown/JSON)
    ├─ Parser: extract name, purpose, inputs, outputs
    ├─ Generator: create skill.yaml, Python, tests, README
    ├─ Validator: check naming conventions
    └─ Output: Complete skill directory structure

Next Steps

After creating a skill with meta.skill:

1. Implement logic - Add functionality to execute() method
2. Write tests - Expand test coverage beyond basic tests
3. Add to agent - Include in agent's skills_available
4. Sync to plugin - Run plugin.sync to update plugin.yaml
5. Test integration - Verify skill works in agent context
6. Document usage - Update README with examples

Related Documentation

• META_AGENTS.md - Meta-agent ecosystem
• ARTIFACT_STANDARDS.md - Artifact system
• skill-description schema
• skill-definition schema

How Claude Uses This

Claude can:

1. Create skills on demand - "Create a skill that validates YAML files"
2. Extend agent capabilities - "Add a JSON validator skill to this agent"
3. Build skill libraries - "Create skills for all common data operations"
4. Prototype quickly - Test ideas by generating skill scaffolds

meta.skill enables rapid skill development and agent expansion!