Skills System: Reusable Agent Capabilities

Overview

Skills are reusable, composable agent capabilities. Instead of monolithic agents, build small skills and combine them.

---

Skill Architecture

Defining a Skill

class Skill:
    """Reusable agent capability"""

    def __init__(self, name: str, description: str):
        self.name = name
        self.description = description
        self.version = "1.0"
        self.required_skills = []  # Dependencies
        self.tools = []
        self.state = {}

    def execute(self, input_data: dict) -> dict:
        """Execute the skill"""
        raise NotImplementedError

    def to_definition(self):
        """Export skill definition"""
        return {
            'name': self.name,
            'description': self.description,
            'version': self.version,
            'tools': [t.definition for t in self.tools],
            'inputSchema': self.input_schema(),
            'outputSchema': self.output_schema()
        }


class ResearchSkill(Skill):
    """Research capability"""

    def __init__(self):
        super().__init__(
            name="research",
            description="Find and analyze information"
        )

        self.tools = [
            WebSearchTool(),
            PaperAnalysisTool(),
            SynthesizeTool()
        ]

    def execute(self, input_data: dict):
        """Research a topic"""

        topic = input_data['topic']
        depth = input_data.get('depth', 'medium')

        # Search for information
        sources = self.tools[0].search(topic)

        # Analyze sources
        findings = self.tools[1].analyze(sources)

        # Synthesize
        summary = self.tools[2].synthesize(findings)

        return {
            'topic': topic,
            'summary': summary,
            'sources': sources
        }

---

Skill Composition

Combining Skills

class SkillComposition:
    """Combine multiple skills"""

    def __init__(self):
        self.skills = {}

    def register_skill(self, skill: Skill):
        """Add skill to composition"""
        self.skills[skill.name] = skill

    def compose(self, *skill_names):
        """Create composite skill"""

        skills = [self.skills[name] for name in skill_names]

        # Check dependencies
        for skill in skills:
            for dep in skill.required_skills:
                if dep not in self.skills:
                    raise ValueError(f"Missing dependency: {dep}")

        return CompositeSkill(skills)


class CompositeSkill(Skill):
    """Multiple skills working together"""

    def __init__(self, skills):
        self.skills = skills
        self.name = "composite_" + "_".join(s.name for s in skills)

    def execute(self, input_data: dict):
        """Execute skills in sequence"""

        result = input_data

        for skill in self.skills:
            # Each skill processes previous result
            result = skill.execute(result)

        return result

---

Skill Discovery & Registration

Marketplace Pattern

class SkillRegistry:
    """Discover and register skills"""

    def __init__(self):
        self.skills = {}  # name → skill definition
        self.versions = {}  # skill → versions

    def register_skill(self, skill: Skill):
        """Register skill"""

        skill_def = skill.to_definition()

        # Store versioned
        if skill.name not in self.versions:
            self.versions[skill.name] = []

        self.versions[skill.name].append(skill.version)
        self.skills[f"{skill.name}@{skill.version}"] = skill_def

    def list_skills(self, category: str = None):
        """Find skills"""

        skills = list(self.skills.values())

        if category:
            skills = [s for s in skills if s.get('category') == category]

        return skills

    def get_skill(self, name: str, version: str = None):
        """Get specific skill"""

        if not version:
            # Latest version
            versions = self.versions[name]
            version = max(versions)

        return self.skills[f"{name}@{version}"]

---

Stateful Skills

Skills with Memory

class StatefulSkill(Skill):
    """Skill that maintains state"""

    def __init__(self):
        super().__init__(
            name="memory_skill",
            description="Skill that remembers things"
        )
        self.memory = {}  # Persistent state

    def remember(self, key: str, value: any):
        """Store in memory"""
        self.memory[key] = value

    def recall(self, key: str):
        """Retrieve from memory"""
        return self.memory.get(key)

    def execute(self, input_data: dict):
        """Execute with state awareness"""

        # Load previous state
        user_id = input_data['user_id']
        user_state = self.recall(f"user_{user_id}")

        # Execute
        result = self.process(input_data, user_state)

        # Save state
        self.remember(f"user_{user_id}", result['state'])

        return result

---

Skill Versioning

Managing Versions

class VersionedSkill:
    """Skill with version management"""

    def __init__(self, name: str, version: str):
        self.name = name
        self.version = version
        self.breaking_changes = False  # v2 incompatible with v1?

    def is_compatible_with(self, other_version: str):
        """Check compatibility"""

        self_major = int(self.version.split('.')[0])
        other_major = int(other_version.split('.')[0])

        # Major version changes break compatibility
        return self_major == other_major

    def migrate_from(self, old_version: str, data: dict):
        """Migrate data from old version"""

        if old_version == '1.0' and self.version == '2.0':
            # Handle migration
            data['new_field'] = 'default'

        return data

---

3 Warnings ⚠️

Warning 1: Skill Coupling

# ❌ WRONG
# Skills tightly coupled
research_skill.depends_on(analysis_skill)
analysis_skill.depends_on(writing_skill)
# Hard to reuse individually

# ✅ RIGHT
# Skills loosely coupled
# Each skill defines input/output contract
# Skills compose through data, not dependencies

Warning 2: State Management

# ❌ WRONG
# Shared mutable state between skills
shared_state = {}
skill_1.use_state(shared_state)
skill_2.use_state(shared_state)  # Race conditions!

# ✅ RIGHT
# Explicit state passing
result_1 = skill_1.execute(input)
result_2 = skill_2.execute(result_1)
# Data flows through return values

Warning 3: Version Hell

# ❌ WRONG
# Multiple incompatible versions running
agent_1.uses("research@1.0")
agent_2.uses("research@2.0")
# Unpredictable behavior

# ✅ RIGHT
# Explicit version management
skill = registry.get_skill("research", version="2.0")
# Pin versions in agent config

---

Last Updated: August 9, 2026