> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.skills

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Exports

| Name | Kind |
| - | - |
| [`CatalogSkill`](#catalogskill) | Class |
| [`DecisionSkillSelector`](#decisionskillselector) | Class |
| [`FilesystemSkillSource`](#filesystemskillsource) | Class |
| [`SkillAccess`](#skillaccess) | Class |
| [`SkillCatalogPage`](#skillcatalogpage) | Class |
| [`SkillContext`](#skillcontext) | Class |
| [`SkillDescriptor`](#skilldescriptor) | Class |
| [`SkillDocument`](#skilldocument) | Class |
| [`SkillError`](#skillerror) | Class |
| [`SkillNotFoundError`](#skillnotfounderror) | Class |
| [`SkillPage`](#skillpage) | Class |
| [`SkillRegistry`](#skillregistry) | Class |
| [`SkillResource`](#skillresource) | Class |
| [`SkillResourceNotSupported`](#skillresourcenotsupported) | Class |
| [`SkillScope`](#skillscope) | Class |
| [`SkillSelectionError`](#skillselectionerror) | Class |
| [`SkillSelectionFallback`](#skillselectionfallback) | Class |
| [`SkillSource`](#skillsource) | Class |
| [`SkillSourceExecutionError`](#skillsourceexecutionerror) | Class |
| [`SkillValidationError`](#skillvalidationerror) | Class |

## CatalogSkill

Attach registry routing identity to source-owned skill metadata.

```python theme={null}
CatalogSkill(source: str, descriptor: SkillDescriptor) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `source` | `str` | `—` |
| `descriptor` | `SkillDescriptor` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `source` | `str` | Required |
> | `descriptor` | `SkillDescriptor` | Required |
>
> ```python theme={null}
> from harnest.skills import CatalogSkill
>
> skill = CatalogSkill(source=..., descriptor=...)
> ```

### CatalogSkill.as\_dict

```python theme={null}
CatalogSkill.as_dict() -> dict[str, str]
```

Return the stable model-facing routing representation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import CatalogSkill
>
> skill: CatalogSkill
> result = skill.as_dict()
> ```

## DecisionSkillSelector

Build bounded decisions from visible skill metadata before a managed model call.

```python theme={null}
DecisionSkillSelector(
    provider: str | None = None,
    instructions: str = 'Select skills needed for the current task; skip unrelated skills.',
    input: SkillSelectionInput | None = None,
    max_skills: int = 3,
    max_candidates: int = 30,
    timeout_seconds: float = 10,
    fallback: SkillSelectionFallback = SkillSelectionFallback.DISCOVERY,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `DISCOVERY` | `ClassVar[SkillSelectionFallback]` | `SkillSelectionFallback.DISCOVERY` |
| `ERROR` | `ClassVar[SkillSelectionFallback]` | `SkillSelectionFallback.ERROR` |
| `provider` | `str \| None` | `None` |
| `instructions` | `str` | `'Select skills needed for the current task; skip unrelated skills.'` |
| `input` | `SkillSelectionInput \| None` | `None` |
| `max_skills` | `int` | `3` |
| `max_candidates` | `int` | `30` |
| `timeout_seconds` | `float` | `10` |
| `fallback` | `SkillSelectionFallback` | `SkillSelectionFallback.DISCOVERY` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `provider` | `str \| None` | `None` |
> | `instructions` | `str` | `'Select skills needed for the current task; skip unrelated skills.'` |
> | `input` | `SkillSelectionInput \| None` | `None` |
> | `max_skills` | `int` | `3` |
> | `max_candidates` | `int` | `30` |
> | `timeout_seconds` | `float` | `10` |
> | `fallback` | `SkillSelectionFallback` | `SkillSelectionFallback.DISCOVERY` |
>
> ```python theme={null}
> from harnest.skills import DecisionSkillSelector
>
> selector = DecisionSkillSelector()
> ```

## FilesystemSkillSource

Serve compiler-validated skills from one agent-owned filesystem scope.

```python theme={null}
FilesystemSkillSource(directories: Sequence[str | Path]) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `directories` | `Sequence[str \| Path]` | Required |
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source = FilesystemSkillSource(directories=...)
> ```

### FilesystemSkillSource.list

```python theme={null}
async FilesystemSkillSource.list(
    context: SkillContext,
    *,
    query: str | None = None,
    cursor: str | None = None,
    limit: int = 50,
) -> SkillPage
```

Page a bounded local catalog in deterministic directory order.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `SkillContext` | Required |
> | `query` | `str \| None` | `None` |
> | `cursor` | `str \| None` | `None` |
> | `limit` | `int` | `50` |
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source: FilesystemSkillSource
> page = await source.list(context=...)
> ```

### FilesystemSkillSource.load

```python theme={null}
async FilesystemSkillSource.load(skill_id: str, context: SkillContext, *, version: str | None = None) -> SkillDocument
```

Read one static manifest after validating its pinned version.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source: FilesystemSkillSource
> document = await source.load(skill_id=..., context=...)
> ```

### FilesystemSkillSource.load\_resource

```python theme={null}
async FilesystemSkillSource.load_resource(
    skill_id: str,
    path: str,
    context: SkillContext,
    *,
    version: str | None = None,
) -> SkillResource
```

Read one regular UTF-8 file without escaping its skill directory.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `path` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source: FilesystemSkillSource
> resource = await source.load_resource(skill_id=..., path=..., context=...)
> ```

### FilesystemSkillSource.descriptors

Expose compile-time routing metadata without loading instructions.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source: FilesystemSkillSource
> value = source.descriptors
> ```

### FilesystemSkillSource.routing\_identity

Distinguish equal content owned by different agent directories.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import FilesystemSkillSource
>
> source: FilesystemSkillSource
> value = source.routing_identity
> ```

## SkillAccess

Public `context.skills` operations bound to the current agent identity.

```python theme={null}
SkillAccess(scope: SkillScope, active: Any) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `SkillScope` | Required |
> | `active` | `Any` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillAccess
>
> access = SkillAccess(scope=..., active=...)
> ```

### SkillAccess.list

```python theme={null}
async SkillAccess.list(
    *,
    source: str | None = None,
    query: str | None = None,
    cursor: str | None = None,
    limit: int = 50,
) -> SkillCatalogPage
```

List metadata visible to this invocation without loading bodies.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `source` | `str \| None` | `None` |
> | `query` | `str \| None` | `None` |
> | `cursor` | `str \| None` | `None` |
> | `limit` | `int` | `50` |
>
> ```python theme={null}
> from harnest.skills import SkillAccess
>
> access: SkillAccess
> page = await access.list()
> ```

### SkillAccess.load

```python theme={null}
async SkillAccess.load(skill_id: str, *, source: str | None = None, version: str | None = None) -> SkillDocument
```

Load one selected skill through this invocation's governed scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `source` | `str \| None` | `None` |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillAccess
>
> access: SkillAccess
> document = await access.load(skill_id=...)
> ```

### SkillAccess.load\_resource

```python theme={null}
async SkillAccess.load_resource(
    skill_id: str,
    path: str,
    *,
    source: str | None = None,
    version: str | None = None,
) -> SkillResource
```

Load one resource through this invocation's governed scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `path` | `str` | Required |
> | `source` | `str \| None` | `None` |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillAccess
>
> access: SkillAccess
> resource = await access.load_resource(skill_id=..., path=...)
> ```

## SkillCatalogPage

A bounded catalog merged from one or more independently paged sources.

```python theme={null}
SkillCatalogPage(
    items: tuple[CatalogSkill, ...],
    next_cursors: Mapping[str, str] = ...,
    truncated: bool = False,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `items` | `tuple[CatalogSkill, ...]` | `—` |
| `next_cursors` | `Mapping[str, str]` | `dict()` |
| `truncated` | `bool` | `False` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `items` | `tuple[CatalogSkill, ...]` | Required |
> | `next_cursors` | `Mapping[str, str]` | `...` |
> | `truncated` | `bool` | `False` |
>
> ```python theme={null}
> from harnest.skills import SkillCatalogPage
>
> page = SkillCatalogPage(items=...)
> ```

### SkillCatalogPage.as\_dict

```python theme={null}
SkillCatalogPage.as_dict() -> dict[str, Any]
```

Return a JSON-safe catalog without including instruction bodies.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillCatalogPage
>
> page: SkillCatalogPage
> result = page.as_dict()
> ```

## SkillContext

Revocable invocation identity passed to every dynamic skill source.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext  # returned by Harnest, not constructed directly
> ```

### SkillContext.task

Return current task text during automatic selection, never prior conversation turns.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.task
> ```

### SkillContext.state

Snapshot JSON application state only when the selection callback requests it.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.state
> ```

### SkillContext.framework

Return the framework active for this invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.framework
> ```

### SkillContext.agent\_name

Return the exact root or subagent currently requesting skills.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.agent_name
> ```

### SkillContext.parent\_agent\_name

Return the immediate parent identity when this is a subagent.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.parent_agent_name
> ```

### SkillContext.depth

Return the managed subagent nesting depth.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.depth
> ```

### SkillContext.invocation\_id

Return the current invocation correlation identity.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.invocation_id
> ```

### SkillContext.user\_id

Return the authenticated runtime user identity.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.user_id
> ```

### SkillContext.claims

Return verified non-secret authentication claims when available.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.claims
> ```

### SkillContext.session\_id

Return the framework-neutral session identity.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.session_id
> ```

### SkillContext.metadata

Return immutable non-secret invocation metadata.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.metadata
> ```

### SkillContext.credentials

Return private credential resolution without copying secret values.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.credentials
> ```

### SkillContext.storage

Return invocation-scoped access to named application storage.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> value = context.storage
> ```

### SkillContext.resource

```python theme={null}
SkillContext.resource(name: str, expected_type: type[Any] | None = None) -> Any
```

Resolve an explicitly exported application resource.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `expected_type` | `type[Any] \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillContext
>
> context: SkillContext
> result = context.resource(name=...)
> ```

## SkillDescriptor

Bounded metadata that lets a model select a skill progressively.

```python theme={null}
SkillDescriptor(id: str, name: str, description: str, version: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `name` | `str` | `—` |
| `description` | `str` | `—` |
| `version` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `id` | `str` | Required |
> | `name` | `str` | Required |
> | `description` | `str` | Required |
> | `version` | `str` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillDescriptor
>
> descriptor = SkillDescriptor(id=..., name=..., description=..., version=...)
> ```

## SkillDocument

One versioned instruction document returned by a skill source.

```python theme={null}
SkillDocument(descriptor: SkillDescriptor, instructions: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `descriptor` | `SkillDescriptor` | `—` |
| `instructions` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `descriptor` | `SkillDescriptor` | Required |
> | `instructions` | `str` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillDocument
>
> document = SkillDocument(descriptor=..., instructions=...)
> ```

## SkillError

Base error for invalid or unavailable skill operations.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillError
>
> try:
>     ...
> except SkillError as error:
>     ...
> ```

## SkillNotFoundError

A requested source, skill, version, or resource is unavailable.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillNotFoundError
>
> try:
>     ...
> except SkillNotFoundError as error:
>     ...
> ```

## SkillPage

One source-owned page that never requires loading skill bodies.

```python theme={null}
SkillPage(items: tuple[SkillDescriptor, ...], next_cursor: str | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `items` | `tuple[SkillDescriptor, ...]` | `—` |
| `next_cursor` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `items` | `tuple[SkillDescriptor, ...]` | Required |
> | `next_cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillPage
>
> page = SkillPage(items=...)
> ```

## SkillRegistry

Route invocation-scoped access to each compiled agent's skill sources.

```python theme={null}
SkillRegistry(scopes: Mapping[str, SkillScope] | None = None) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scopes` | `Mapping[str, SkillScope] \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillRegistry
>
> registry = SkillRegistry()
> ```

### SkillRegistry.agent\_names

Return compiled identities for diagnostics without exposing sources.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillRegistry
>
> registry: SkillRegistry
> value = registry.agent_names
> ```

### SkillRegistry.scope

```python theme={null}
SkillRegistry.scope(agent_name: str) -> SkillScope
```

Return one immutable compiled scope for runtime-safe augmentation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `agent_name` | `str` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillRegistry
>
> registry: SkillRegistry
> scope = registry.scope(agent_name=...)
> ```

### SkillRegistry.access

```python theme={null}
SkillRegistry.access(active: Any) -> 'SkillAccess'
```

Bind a registry view to one revocable invocation context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `active` | `Any` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillRegistry
>
> registry: SkillRegistry
> access = registry.access(active=...)
> ```

## SkillResource

One bounded UTF-8 supporting resource for a selected skill version.

```python theme={null}
SkillResource(skill_id: str, version: str, path: str, content: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `skill_id` | `str` | `—` |
| `version` | `str` | `—` |
| `path` | `str` | `—` |
| `content` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `version` | `str` | Required |
> | `path` | `str` | Required |
> | `content` | `str` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillResource
>
> resource = SkillResource(skill_id=..., version=..., path=..., content=...)
> ```

## SkillResourceNotSupported

A source deliberately does not expose supporting resources.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillResourceNotSupported
>
> try:
>     ...
> except SkillResourceNotSupported as error:
>     ...
> ```

## SkillScope

Compose named sources for one compiled agent or subagent identity.

```python theme={null}
SkillScope(sources: Mapping[str, SkillSource] | None = None) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `sources` | `Mapping[str, SkillSource] \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope = SkillScope()
> ```

### SkillScope.source\_names

Return stable source identities without exposing provider objects.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> value = scope.source_names
> ```

### SkillScope.routing\_identity

Compare repeated compiler composition without equating remote clients.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> value = scope.routing_identity
> ```

### SkillScope.with\_filesystem\_directories

```python theme={null}
SkillScope.with_filesystem_directories(directories: Sequence[str | Path]) -> 'SkillScope'
```

Return a scope whose filesystem route also owns new immutable skills.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `directories` | `Sequence[str \| Path]` | Required |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> scope = scope.with_filesystem_directories(directories=...)
> ```

### SkillScope.list

```python theme={null}
async SkillScope.list(
    context: SkillContext,
    *,
    source: str | None = None,
    query: str | None = None,
    cursor: str | None = None,
    limit: int = 50,
) -> SkillCatalogPage
```

List one source page or merge first pages without per-skill queries.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `SkillContext` | Required |
> | `source` | `str \| None` | `None` |
> | `query` | `str \| None` | `None` |
> | `cursor` | `str \| None` | `None` |
> | `limit` | `int` | `50` |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> page = await scope.list(context=...)
> ```

### SkillScope.load

```python theme={null}
async SkillScope.load(
    skill_id: str,
    context: SkillContext,
    *,
    source: str | None = None,
    version: str | None = None,
) -> SkillDocument
```

Load one document through an explicit or unambiguous source.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `source` | `str \| None` | `None` |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> document = await scope.load(skill_id=..., context=...)
> ```

### SkillScope.load\_resource

```python theme={null}
async SkillScope.load_resource(
    skill_id: str,
    path: str,
    context: SkillContext,
    *,
    source: str | None = None,
    version: str | None = None,
) -> SkillResource
```

Load one bounded resource through an exact source route.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `path` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `source` | `str \| None` | `None` |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> resource = await scope.load_resource(skill_id=..., path=..., context=...)
> ```

### SkillScope.selected\_source

```python theme={null}
SkillScope.selected_source(source: str | None = None) -> str
```

Resolve the route used by context access and model-tool shorthand.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `source` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillScope
>
> scope: SkillScope
> result = scope.selected_source()
> ```

## SkillSelectionError

Selection failed without exposing source, callback, or provider payloads.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillSelectionError
>
> try:
>     ...
> except SkillSelectionError as error:
>     ...
> ```

## SkillSelectionFallback

Closed failure modes; ordinary discovery remains available by default.

```python theme={null}
SkillSelectionFallback(*values)
```

| Member | Value |
| - | - |
| `DISCOVERY` | `'discovery'` |
| `ERROR` | `'error'` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillSelectionFallback
>
> value = SkillSelectionFallback.DISCOVERY
> ```

## SkillSource

Base class for bounded, authorization-aware progressive skill providers.

```python theme={null}
SkillSource()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillSource
>
> class MySkillSource(SkillSource):
>     ...
> ```

### SkillSource.list

```python theme={null}
async SkillSource.list(
    context: SkillContext,
    *,
    query: str | None = None,
    cursor: str | None = None,
    limit: int = 50,
) -> SkillPage
```

Return only descriptors visible to the active agent and principal.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `SkillContext` | Required |
> | `query` | `str \| None` | `None` |
> | `cursor` | `str \| None` | `None` |
> | `limit` | `int` | `50` |
>
> ```python theme={null}
> from harnest.skills import SkillSource
>
> source: SkillSource
> page = await source.list(context=...)
> ```

### SkillSource.load

```python theme={null}
async SkillSource.load(skill_id: str, context: SkillContext, *, version: str | None = None) -> SkillDocument
```

Load one authorized versioned instruction document.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillSource
>
> source: SkillSource
> document = await source.load(skill_id=..., context=...)
> ```

### SkillSource.load\_resource

```python theme={null}
async SkillSource.load_resource(
    skill_id: str,
    path: str,
    context: SkillContext,
    *,
    version: str | None = None,
) -> SkillResource
```

Load one supporting resource when this source exposes them.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `skill_id` | `str` | Required |
> | `path` | `str` | Required |
> | `context` | `SkillContext` | Required |
> | `version` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.skills import SkillSource
>
> source: SkillSource
> resource = await source.load_resource(skill_id=..., path=..., context=...)
> ```

## SkillSourceExecutionError

A source operation failed across the governed runtime boundary.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillSourceExecutionError
>
> try:
>     ...
> except SkillSourceExecutionError as error:
>     ...
> ```

## SkillValidationError

A source or skill value violates the portable contract.

> [accordion] Example
>
> ```python theme={null}
> from harnest.skills import SkillValidationError
>
> try:
>     ...
> except SkillValidationError as error:
>     ...
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.