Skills System
=============

PyGEAI includes a comprehensive Skills System that provides AI coding agents with expert knowledge about the SDK. Skills are structured documentation packages that teach agents how to effectively use PyGEAI features.

Overview
--------

The Skills System consists of:

* **17 built-in skills** covering all PyGEAI features
* **SkillsEngine** for loading and managing skills
* **AgentDetector** for finding installed coding agents
* **SkillInstaller** for deploying skills to agents
* **SkillValidator** for ensuring skill quality

Each skill includes:

* Comprehensive SKILL.md documentation (400-700+ lines)
* CLI usage examples with bash commands
* Python client usage with code examples
* Real-world examples (3-6 per skill)
* Best practices and troubleshooting guides
* Supporting files (scripts, references, assets)

Architecture
------------

Skills Directory Structure
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

    pygeai/skills/
    ├── __init__.py
    ├── models.py           # Skill and Agent dataclasses
    ├── engine.py           # SkillsEngine for loading skills
    ├── validator.py        # SKILL.md validation
    ├── detector.py         # Agent detection
    ├── installer.py        # Skill installation
    └── builtin/            # Built-in skills
        ├── geai-llm-expert/
        │   ├── SKILL.md
        │   ├── scripts/
        │   ├── references/
        │   └── assets/
        ├── geai-rag-assistant/
        │   ├── SKILL.md
        │   ├── scripts/
        │   ├── references/
        │   └── assets/
        └── ...

SKILL.md Format
^^^^^^^^^^^^^^^

Each skill follows the agentskills.io specification:

.. code-block:: yaml

    ---
    name: geai-llm-expert
    version: 1.0.0
    description: Master LLM providers, models, parameters, and prompt engineering
    categories:
      - llm
      - models
      - prompting
    tags:
      - llm
      - models
      - parameters
    agents:
      - opencode
      - claude
      - codex
      - cursor
      - coda-cli
    author: PyGEAI Team
    license: MIT
    ---

    # Skill Content

    ## Overview
    Skill overview and introduction

    ## Capabilities
    List of capabilities

    ## CLI Usage
    Command-line examples

    ## Python Client Usage
    Python code examples

    ## Examples
    Real-world usage examples

    ## Best Practices
    Recommendations and tips

Built-in Skills
---------------

PyGEAI includes 17 production-ready skills:

**Agent Management** (2 skills)
  * ``geai-agent-creator`` - Creating and configuring agents
  * ``geai-agent-manager`` - Managing agent lifecycle

**Analytics** (1 skill)
  * ``geai-analytics`` - Usage tracking and monitoring

**CLI** (1 skill)
  * ``geai-cli-expert`` - Command-line interface mastery

**Configuration** (1 skill)
  * ``geai-configuration`` - Environment and credentials setup

**Embeddings** (1 skill)
  * ``geai-embeddings`` - Vector embeddings and semantic search

**Evaluation** (1 skill)
  * ``geai-evaluator`` - Model evaluation and testing

**Files** (1 skill)
  * ``geai-file-manager`` - File upload and management

**Generation** (1 skill)
  * ``geai-project-generator`` - Project scaffolding

**LLM** (1 skill)
  * ``geai-llm-expert`` - Language model expertise

**Parsing** (1 skill)
  * ``geai-omni-parser`` - Multimodal content extraction

**Processes** (2 skills)
  * ``geai-process-designer`` - Workflow design
  * ``geai-process-executor`` - Workflow execution

**RAG** (1 skill)
  * ``geai-rag-assistant`` - Retrieval-augmented generation

**Security** (1 skill)
  * ``geai-secrets-manager`` - Secrets management

**Tools** (2 skills)
  * ``geai-tool-builder`` - Custom tool creation
  * ``geai-tool-manager`` - Tool registry and lifecycle

Basic Usage
-----------

Loading Skills
^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    # Initialize the skills engine
    engine = SkillsEngine()

    # List all built-in skills
    skills = engine.list_builtin_skills()
    print(f"Loaded {len(skills)} skills")

    # Output: Loaded 17 skills

Get Specific Skill
^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Get a specific skill by name
    skill = engine.get_skill("geai-llm-expert")
    
    print(f"Name: {skill.name}")
    print(f"Version: {skill.version}")
    print(f"Description: {skill.description}")
    print(f"Categories: {', '.join(skill.categories)}")

    # Output:
    # Name: geai-llm-expert
    # Version: 1.0.0
    # Description: Master LLM providers, models, parameters, prompt engineering...
    # Categories: llm, models, prompting

Filter by Category
^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Get all RAG-related skills
    rag_skills = engine.list_builtin_skills(category="rag")
    
    print(f"RAG skills: {len(rag_skills)}")
    for skill in rag_skills:
        print(f"  - {skill.name}")

    # Output:
    # RAG skills: 1
    #   - geai-rag-assistant

List All Categories
^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Group skills by category
    categories = engine.list_categories()
    
    for category, skills in sorted(categories.items()):
        print(f"{category}: {len(skills)} skill(s)")

    # Output:
    # agents: 2 skill(s)
    # analytics: 1 skill(s)
    # cli: 1 skill(s)
    # configuration: 1 skill(s)
    # embeddings: 1 skill(s)
    # evaluation: 1 skill(s)
    # files: 1 skill(s)
    # generation: 1 skill(s)
    # llm: 1 skill(s)
    # parsing: 1 skill(s)
    # processes: 2 skill(s)
    # rag: 1 skill(s)
    # security: 1 skill(s)
    # tools: 2 skill(s)

Agent Detection
^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Detect installed coding agents
    agents = engine.detect_agents()
    
    print(f"Detected {len(agents)} coding agent(s)")
    for agent in agents:
        print(f"  - {agent.name} at {agent.skills_path}")

    # List supported agents
    supported = engine.get_supported_agents()
    print(f"Supported: {', '.join(supported)}")

    # Output:
    # Supported: opencode, claude-code, codex, cursor, coda-cli

Advanced Usage
--------------

Installing Skills
^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Get a skill
    skill = engine.get_skill("geai-llm-expert")
    
    # Detect agents
    agents = engine.detect_agents()
    
    # Install to detected agents
    results = engine.install_skill(skill, agents=agents)
    
    for agent_name, success in results.items():
        status = "Success" if success else "Failed"
        print(f"{agent_name}: {status}")

Validating Skills
^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine
    from pathlib import Path

    engine = SkillsEngine()
    
    # Validate a skill directory
    skill_path = Path("pygeai/skills/builtin/geai-llm-expert")
    is_valid, errors = engine.validate_skill(skill_path)
    
    if is_valid:
        print("Skill is valid")
    else:
        print("Validation errors:")
        for error in errors:
            print(f"  - {error}")

Accessing Skill Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    skill = engine.get_skill("geai-llm-expert")
    
    # Access skill attributes
    print(f"Name: {skill.name}")
    print(f"Version: {skill.version}")
    print(f"Description: {skill.description}")
    print(f"Categories: {skill.categories}")
    print(f"Tags: {skill.tags}")
    print(f"Author: {skill.author}")
    print(f"License: {skill.license}")

Listing Skill Files
^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine
    from pathlib import Path

    engine = SkillsEngine()
    skill = engine.get_skill("geai-llm-expert")
    
    # List supporting files
    skill_dir = Path(f"pygeai/skills/builtin/{skill.name}")
    
    print("Scripts:")
    for script in (skill_dir / "scripts").glob("*"):
        print(f"  - {script.name}")
    
    print("\nReferences:")
    for ref in (skill_dir / "references").glob("*"):
        print(f"  - {ref.name}")
    
    print("\nAssets:")
    for asset in (skill_dir / "assets").glob("*"):
        print(f"  - {asset.name}")

CLI Usage
---------

Skills Setup Wizard
^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    # Interactive setup wizard
    geai skills setup

    # The wizard will:
    # 1. Detect installed coding agents
    # 2. Show available skills
    # 3. Let you select skills to install
    # 4. Install selected skills

List Skills
^^^^^^^^^^^

.. code-block:: bash

    # List all available skills
    geai skills list

    # List skills by category
    geai skills list --category llm
    geai skills list --category rag

    # Show installed skills
    geai skills list --installed

Skill Information
^^^^^^^^^^^^^^^^^

.. code-block:: bash

    # Show detailed information about a skill
    geai skills info geai-llm-expert

    # Output includes:
    # - Name and version
    # - Description
    # - Categories and tags
    # - Supported agents
    # - File locations

Install Skills
^^^^^^^^^^^^^^

.. code-block:: bash

    # Install skill to all detected agents
    geai skills install geai-llm-expert

    # Install to specific agent
    geai skills install geai-llm-expert --agent claude

    # Global installation
    geai skills install geai-llm-expert --global

Validate Skills
^^^^^^^^^^^^^^^

.. code-block:: bash

    # Validate a specific skill
    geai skills validate --skill geai-llm-expert

    # Validate all skills
    geai skills validate --all

Creating Custom Skills
----------------------

Skill Template
^^^^^^^^^^^^^^

Create a new skill using this template:

.. code-block:: bash

    # Create skill directory
    mkdir -p my-custom-skill/{scripts,references,assets}

    # Create SKILL.md with frontmatter
    cat > my-custom-skill/SKILL.md << 'EOF'
    ---
    name: my-custom-skill
    version: 1.0.0
    description: My custom skill description
    categories:
      - custom
    tags:
      - custom
      - example
    agents:
      - opencode
      - claude
      - codex
      - cursor
      - coda-cli
    author: Your Name
    license: MIT
    ---

    # My Custom Skill

    ## Overview
    Description of your skill

    ## Capabilities
    What the skill teaches

    ## CLI Usage
    Command-line examples

    ## Python Client Usage
    Python code examples

    ## Examples
    Real-world usage examples

    ## Best Practices
    Recommendations
    EOF

Skill Structure Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A valid skill must have:

1. **SKILL.md** with valid YAML frontmatter
2. **Required frontmatter fields**: name, version, description, categories
3. **Required sections**: Overview, Capabilities, CLI Usage, Python Client Usage, Examples
4. **Supporting directories**: scripts/, references/, assets/
5. **Code examples**: At least 3 Python blocks and 1 Bash block

Best Practices
--------------

Skill Design
^^^^^^^^^^^^

* **Single focus**: Each skill should cover one specific area
* **Comprehensive**: Include CLI, Python, and real-world examples
* **Actionable**: Provide working code that agents can use
* **Consistent**: Follow the same structure across all skills

Documentation Quality
^^^^^^^^^^^^^^^^^^^^^

* **Clear descriptions**: Explain what the skill teaches
* **Working examples**: All code examples should be tested
* **Best practices**: Include recommendations and tips
* **Error handling**: Show how to handle common errors

Code Examples
^^^^^^^^^^^^^

* **Tested code**: Every example should work as-is
* **Type hints**: Include type hints in Python examples
* **Comments**: Explain complex code sections
* **Complete**: Don't use placeholders or "..."

Metadata
^^^^^^^^

* **Accurate categories**: Choose appropriate categories
* **Descriptive tags**: Use tags that help with search
* **Version tracking**: Increment version on changes
* **Agent support**: List all compatible agents

API Reference
-------------

SkillsEngine
^^^^^^^^^^^^

.. code-block:: python

    class SkillsEngine:
        """Main engine for skills management."""
        
        def list_builtin_skills(self, category: Optional[str] = None) -> List[Skill]:
            """List built-in skills, optionally filtered by category."""
        
        def list_categories(self) -> Dict[str, List[Skill]]:
            """Group skills by category."""
        
        def get_skill(self, skill_name: str) -> Optional[Skill]:
            """Get a specific skill by name."""
        
        def detect_agents(self) -> List[Agent]:
            """Detect installed coding agents."""
        
        def get_supported_agents(self) -> List[str]:
            """Get list of supported agent names."""
        
        def install_skill(
            self,
            skill: Skill,
            agents: Optional[List[Agent]] = None,
            global_install: bool = False,
        ) -> Dict[str, bool]:
            """Install skill to agent(s)."""
        
        def validate_skill(self, skill_path: Path) -> tuple[bool, List[str]]:
            """Validate skill structure and format."""

Skill Model
^^^^^^^^^^^

.. code-block:: python

    @dataclass
    class Skill:
        """Represents a PyGEAI skill."""
        
        name: str
        version: str
        description: str
        categories: List[str]
        metadata: Dict[str, Any]
        path: Path
        
        @property
        def category(self) -> str:
            """Primary category (first in categories list)."""

Agent Model
^^^^^^^^^^^

.. code-block:: python

    @dataclass
    class Agent:
        """Represents a coding agent."""
        
        name: str
        skills_path: Path
        config_path: Optional[Path] = None
        is_installed: bool = True

Troubleshooting
---------------

Skills Not Loading
^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    skills = engine.list_builtin_skills()
    
    if not skills:
        print("No skills found. Check installation:")
        print(f"Builtin path: {engine.builtin_path}")
        print(f"Exists: {engine.builtin_path.exists()}")

Validation Errors
^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine
    from pathlib import Path

    engine = SkillsEngine()
    skill_path = Path("path/to/skill")
    
    is_valid, errors = engine.validate_skill(skill_path)
    
    if not is_valid:
        print("Validation failed:")
        for error in errors:
            print(f"  - {error}")

Agent Detection Issues
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.skills import SkillsEngine

    engine = SkillsEngine()
    
    # Check supported agents
    supported = engine.get_supported_agents()
    print(f"Supported agents: {supported}")
    
    # Try detecting
    detected = engine.detect_agents()
    print(f"Detected agents: {len(detected)}")
    
    if not detected:
        print("No agents detected. Install one of:")
        for agent in supported:
            print(f"  - {agent}")

Statistics
----------

The PyGEAI Skills System includes:

* **17 built-in skills** covering all SDK features
* **10,393 lines** of comprehensive documentation
* **208 Python code examples** across all skills
* **125 Bash code examples** for CLI usage
* **Average 611 lines** per skill
* **80+ supporting files** (scripts, references, assets)
* **100% coverage** of PyGEAI features

All skills are:

* Production-ready with tested examples
* Standards-compliant (agentskills.io)
* Multi-agent compatible
* Fully documented with best practices

See Also
--------

* :doc:`quickstart` - Getting started with PyGEAI
* :doc:`samples` - Usage examples
* :doc:`templates` - Templates and patterns
* :doc:`cli` - CLI reference
