pyskills API

API details

Overview

A plugin system allowing Python packages to register “skills” — units of LLM-usable functionality — via standard Python entry points. An LLM host (e.g. solveit) discovers available pyskills without importing them, reads lightweight descriptions via AST inspection, and selectively loads chosen pyskills into context.

Entry Point Convention

Packages register pyskills under the group pyskills:

[project.entry-points.pyskills]
my_skill = "mypackage.skill"

The value is a module path (no :attribute needed). The module’s docstring first paragraph serves as the pyskill description.

Skill Module Contract

A pyskill module MUST have:

• Docstring — first paragraph is the short description shown to the LLM for pyskill selection; remaining will be read by the LLM to get full details on the pyskill.

A pyskill module MAY have:

• __all__ — the available symbols imported.

Discovery API

def list_pyskills() -> dict[str, str]

Returns {name: description} for all registered pyskills, using find_spec + AST parsing — no imports.

import mypackage.skill

Standard python native import

doc(mypackage.skill)       # module overview: classes, functions, submodules, allows
doc(SomeClass)             # class detail: bases, __init__, methods, properties
doc(some_func)             # function detail: full signature with docments
xdir(mypackage.skill)      # filtered names for public symbols

Inspect at increasing detail — works on any Python module, not just pyskills.

Host Integration

The host (e.g. solveit, claude code, codex, …) would:

1. Call list_pyskills() at startup to build a pyskill catalogue
2. Include the list with each prompt
3. Call import {module} followed by doc({module}) for chosen pyskills

Listing pyskills

ep = entry_points()
es = first(ep.select(group='pyskills', name='pyskills.skill'))
es

EntryPoint(name='pyskills.skill', value='pyskills.skill', group='pyskills')

---

source

ep_desc

def ep_desc(
    ep
):

First paragraph of docstring for entry point ep, without importing it

print(ep_desc(es))

Pyskills is a plugin system allowing Python packages to register "skills" (units of LLM-usable functionality) via standard Python entry points. An LLM host (e.g. solveit) discovers available pyskills without importing them, reads lightweight descriptions via AST inspection, and selectively loads chosen pyskills into context using standard imports.

---

source

list_pyskills

def list_pyskills(
    
):

Returns {module: description} for all pyskills. To load a module, use import {module} then view `doc({module}). NB: pyskills are THE critical way to extend functionality. ALWAYS check for pyskills to help with tasks. If unsure whether a particular pyskill might help, load it and grabs its docs to see!

list_pyskills()

{'pyskills.edit': 'Text editing tools for modifying files and ipynb notebook cells. Each operation — insert, replace, delete lines, and string(s) replacement — has both a `file_*` and `cell_*` variant. All return unified diffs showing what changed, or `"none: No changes."`, or `"error: ..."`.',
 'pyskills.skill': 'Pyskills is a plugin system allowing Python packages to register "skills" (units of LLM-usable functionality) via standard Python entry points. An LLM host (e.g. solveit) discovers available pyskills without importing them, reads lightweight descriptions via AST inspection, and selectively loads chosen pyskills into context using standard imports.'}

allow

---

source

allow

def allow(
    c:VAR_POSITIONAL, allow_policy:NoneType=None, # Callable that raises if call not allowed
):

Add all items in c to __pytools__, optionally constrained by allow_policy

__pytools__ is a defaultdict(set) mapping classes/modules to their allowed method/function names (or ... for all public methods). Values can be plain strings or (name, AllowPolicy) tuples for allow-checked methods. allow registers entries — callables are added under their module, dicts go directly into __pytools__.

def _test_fn(): pass
_test_fn.__module__ = '__main__'
_test_fn.__name__ = 'my_test_func'
allow(_test_fn)
assert 'my_test_func' in __pytools__[sys.modules['__main__']]
allow({str: ['zfill']})
assert 'zfill' in __pytools__[str]
allow({list: ...})
assert ... in __pytools__[list]
__pytools__[sys.modules['__main__']].discard('my_test_func')


allow(collections.Counter.most_common)
assert 'most_common' in __pytools__[collections.Counter]
__pytools__[collections.Counter].discard('most_common')

Allow policies

---

source

chk_dest

def chk_dest(
    p, ok_dests
):

Call self as a function.

chk_dest resolves a path and verifies it falls under one of the allowed destination prefixes. Raises PermissionError if not. Used by all AllowPolicy subclasses.

chk_dest('/tmp/foo.txt', ['/tmp'])
chk_dest('~/tmp/foo.txt', [Path.home()/'tmp'])
try: chk_dest('/etc/passwd', ['/tmp'])
except PermissionError: print("Correctly blocked /etc/passwd")

Correctly blocked /etc/passwd

---

source

OpenWritePolicy

def OpenWritePolicy(
    args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):

Check open() only when mode is writable

---

source

PathWritePolicy

def PathWritePolicy(
    target_pos:NoneType=None, target_kw:NoneType=None
):

Check resolved Path self, optionally also target args

---

source

PosAllowPolicy

def PosAllowPolicy(
    pos:int=0, kw:NoneType=None
):

Check positional/keyword arg is an allowed destination

---

source

AllowPolicy

def AllowPolicy(
    args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):

Base for allow destination policies

Three AllowPolicy subclasses handle different allow-checking patterns.

pp = PosAllowPolicy(1, 'dst')
pp(None, ['src', '/tmp/ok'], {}, ['/tmp'])
try: pp(None, ['src', '/root/bad'], {}, ['/tmp'])
except PermissionError: print("PosAllowPolicy blocked /root/bad")

pwp = PathWritePolicy()
pwp(Path('/tmp/f.txt'), [], {}, ['/tmp'])
try: pwp(Path('/etc/f.txt'), [], {}, ['/tmp'])
except PermissionError: print("PathWritePolicy blocked /etc/f.txt")

owp = OpenWritePolicy()
owp(None, ['/tmp/f.txt', 'w'], {}, ['/tmp'])
owp(None, ['/etc/passwd', 'r'], {}, ['/tmp'])
try: owp(None, ['/root/f.txt', 'w'], {}, ['/tmp'])
except PermissionError: print("OpenWritePolicy blocked write to /root/f.txt")

PosAllowPolicy blocked /root/bad
PathWritePolicy blocked /etc/f.txt
OpenWritePolicy blocked write to /root/f.txt

Allow policies are stored as (name, AllowPolicy) tuples directly inside __pytools__ sets.

doc / xdir

import pyskills.skill

assert _is_own(pyskills.skill, 'skill_test_func')
assert _is_own(pyskills.skill, 'SkillTestClass')
assert not _is_own(pyskills.skill, 'inspect')
assert not _is_own(pyskills.skill, '_private')

xdir returns filtered (name, obj) pairs for a module’s public symbols (respecting __all__, skipping private names), or a class’s __init__ and public methods. For modules, it also includes sibling submodules explicitly imported by the module.

---

source

xdir

def xdir(
    sym
):

Filtered names for public symbols of a module or class (or anything with __dir__)

xdir(pyskills.skill)

['SkillTestClass', 'skill_test_func', 'pyskills.createskill']

---

source

doc

def doc(
    sym
)->str:

Call self as a function.

For a function, doc renders the docstring and full signature with docments (parameter comments):

print(doc(pyskills.skill.skill_test_func))

def skill_test_func(
    x:int=0, # the input
)->str: # the output
"""A test function"""

For a class, doc shows the class hierarchy, docstring, __init__ signature, and all public methods/properties with their first docstring line:

print(doc(pyskills.skill.SkillTestClass))

class SkillTestClass(str):
    """Some class.
    More info about it."""
    def __init__(self): ...
    def f(self, x: int = 0) -> str: ...  # A test method
    @property
    def g(self) -> str: ...  # A test prop

For a module, doc shows the docstring, all public classes and functions with their signatures and first docstring line, submodules, and any allow() calls:

print(doc(pyskills.skill)[-450:])

## Creating pyskills

`from pyskills import createskill; doc(createskill)` for how to build and register your own pyskill modules, including the allow/policy system.
"""

## types:
- class SkillTestClass(str): ...  # Some class.

## functions:
- def skill_test_func(x: int = 0) -> str: ...  # A test function

## submodules:
  pyskills.createskill: ...  # How to create a pyskills pyskill module.

## allows:
- allow(skill_test_func, SkillTestClass)

class Pet:
    def __init__(self, name, sound):
        self.name,self.sound = name,sound
    def speak(self):
        "Make the pet's sound"
        return f'{self.name} says {self.sound}!'
    def __dir__(self): return ['name', 'sound', 'speak']

p = Pet('Rex', 'woof')
print(doc(p))

Instance of type Pet:
- name: str = 'Rex'
- sound: str = 'woof'
- speak()  # Make the pet's sound

---

source

docfind

def docfind(
    o, q, n:int=2, _pre:str=''
):

Search doc() recursively through xdir(o), looking at submodules, classes, and functions, to depth n

Skills registration

Pyskills can be added as standard modules with pyproject entrypoints. But for convenience, they can also be added to a custom pyskills XDG directory, which is automatically added to sys.path.

---

source

ensure_pyskills_dir

def ensure_pyskills_dir(
    
):

Create xdg pyskills dir and .pth file if needed

---

source

pyskills_dir

def pyskills_dir(
    
):

Directory for user pyskills

pyskills_dir returns the XDG data home path for user pyskills. ensure_pyskills_dir creates that directory if needed and writes a .pth file into site-packages so Python automatically adds it to sys.path. You can drop pyskill modules there without manual path configuration and which can be available across venvs.

---

source

clear_mod

def clear_mod(
    prefix
):

Clear modules starting with prefix from python caches

clear_mod purges all cached modules matching a prefix from sys.modules and invalidates import caches, ensuring a fresh import on next access. Used after enabling/disabling pyskills so changes take effect immediately.

---

source

register_pyskill

def register_pyskill(
    name, docstr, code:str=''
):

Register a pyskill module name in the xdg pyskills dir

---

source

enable_pyskill

def enable_pyskill(
    name
):

Enable pyskill name by creating its dist-info entry point

enable_pyskill creates a minimal dist-info directory with an entry point so the pyskill is listed. register_pyskill also writes an actual module file (with docstring and code) into the pyskills directory, and creates any needed __init__.py files for nested packages.

This lets you programmatically create and register a pyskill without a full package install.

---

source

disable_pyskill

def disable_pyskill(
    name
):

Disable pyskill name by removing its dist-info entry point

disable_pyskill removes the dist-info directory for a pyskill, so it no longer appears in entry point discovery. It also clears the module cache so the pyskill is fully unloaded.

---

source

delete_pyskill

def delete_pyskill(
    name
):

Delete pyskill name module files and dist-info