Skip to content

Skills API

The Skills system allows you to create reusable workflows and custom commands.

Skills Management

discover_skills

patchpal.skills.discover_skills(repo_root=None)

Discover all available skills from personal and project directories.

Parameters:

Name Type Description Default
repo_root Optional[Path]

Repository root path (for project-specific skills)

 None

Returns:

Type Description
Dict[str, Skill]

Dictionary mapping skill names to Skill objects
Source code in patchpal/skills.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def discover_skills(repo_root: Optional[Path] = None) -> Dict[str, Skill]:
    """Discover all available skills from personal and project directories.

    Args:
        repo_root: Repository root path (for project-specific skills)

    Returns:
        Dictionary mapping skill names to Skill objects
    """
    skills = {}

    # Personal skills: ~/.patchpal/skills/
    personal_skills_dir = Path.home() / ".patchpal" / "skills"
    if personal_skills_dir.exists():
        for skill_dir in personal_skills_dir.iterdir():
            if skill_dir.is_dir():
                skill_file = skill_dir / "SKILL.md"
                if skill_file.exists():
                    skill = _parse_skill_file(skill_file)
                    if skill:
                        skills[skill.name] = skill

    # Project-specific skills: <repo>/.patchpal/skills/
    if repo_root:
        project_skills_dir = repo_root / ".patchpal" / "skills"
        if project_skills_dir.exists():
            for skill_dir in project_skills_dir.iterdir():
                if skill_dir.is_dir():
                    skill_file = skill_dir / "SKILL.md"
                    if skill_file.exists():
                        skill = _parse_skill_file(skill_file)
                        if skill:
                            # Project skills override personal skills
                            skills[skill.name] = skill

    return skills

list_skills

patchpal.skills.list_skills(repo_root=None)

Get a list of all available skills.

Parameters:

Name Type Description Default
repo_root Optional[Path]

Repository root path

 None

Returns:

Type Description
List[Skill]

List of Skill objects sorted by name
Source code in patchpal/skills.py 
111
112
113
114
115
116
117
118
119
120
121
def list_skills(repo_root: Optional[Path] = None) -> List[Skill]:
    """Get a list of all available skills.

    Args:
        repo_root: Repository root path

    Returns:
        List of Skill objects sorted by name
    """
    skills = discover_skills(repo_root)
    return sorted(skills.values(), key=lambda s: s.name)

get_skill

patchpal.skills.get_skill(name, repo_root=None)

Get a specific skill by name.

Parameters:

Name Type Description Default
name str

Skill name

 required
repo_root Optional[Path]

Repository root path

 None

Returns:

Type Description
Optional[Skill]

Skill object or None if not found
Source code in patchpal/skills.py 
124
125
126
127
128
129
130
131
132
133
134
135
def get_skill(name: str, repo_root: Optional[Path] = None) -> Optional[Skill]:
    """Get a specific skill by name.

    Args:
        name: Skill name
        repo_root: Repository root path

    Returns:
        Skill object or None if not found
    """
    skills = discover_skills(repo_root)
    return skills.get(name)

Skill Class

patchpal.skills.Skill(name, description, instructions, path)

Represents a PatchPal skill.

Source code in patchpal/skills.py 
16
17
18
19
20
def __init__(self, name: str, description: str, instructions: str, path: Path):
    self.name = name
    self.description = description
    self.instructions = instructions
    self.path = path

Usage Example

from patchpal.skills import list_skills, get_skill

# List all available skills
skills = list_skills()
for skill in skills:
    print(f"/{skill.name} - {skill.description}")

# Get a specific skill
skill = get_skill("commit")
if skill:
    print(f"Name: {skill.name}")
    print(f"Description: {skill.description}")
    print(f"Instructions:\n{skill.instructions}")

Creating Skills Programmatically

While skills are typically defined as markdown files, you can also work with them programmatically:

from pathlib import Path
from patchpal.skills import discover_skills

# Discover all skills in the repository and personal directories
repo_root = Path.cwd()
skills_dict = discover_skills(repo_root)

# Skills are keyed by name
for skill_name, skill in skills_dict.items():
    print(f"{skill_name}: {skill.description}")

Skill File Format

Skills are markdown files with YAML frontmatter:

---
name: myskill
description: A custom skill that does something useful
---

Instructions for the agent...

1. First do this
2. Then do that
3. Finally, complete the task