harnest.skills

All Python modules · Import and compatibility guidance

Exports

Name	Kind
`CatalogSkill`	Class
`DecisionSkillSelector`	Class
`FilesystemSkillSource`	Class
`SkillAccess`	Class
`SkillCatalogPage`	Class
`SkillContext`	Class
`SkillDescriptor`	Class
`SkillDocument`	Class
`SkillError`	Class
`SkillNotFoundError`	Class
`SkillPage`	Class
`SkillRegistry`	Class
`SkillResource`	Class
`SkillResourceNotSupported`	Class
`SkillScope`	Class
`SkillSelectionError`	Class
`SkillSelectionFallback`	Class
`SkillSource`	Class
`SkillSourceExecutionError`	Class
`SkillValidationError`	Class

CatalogSkill

Attach registry routing identity to source-owned skill metadata.

CatalogSkill(source: str, descriptor: SkillDescriptor) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`source`	`str`	Required
`descriptor`	`SkillDescriptor`	Required

from harnest.skills import CatalogSkill

skill = CatalogSkill(source=..., descriptor=...)

CatalogSkill.as_dict

CatalogSkill.as_dict() -> dict[str, str]

Return the stable model-facing routing representation.

Example

from harnest.skills import CatalogSkill

skill: CatalogSkill
result = skill.as_dict()

DecisionSkillSelector

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

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`

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`

from harnest.skills import DecisionSkillSelector

selector = DecisionSkillSelector()

FilesystemSkillSource

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

FilesystemSkillSource(directories: Sequence[str | Path]) -> None

Parameters and example

Parameter	Type	Default
`directories`	`Sequence[str \| Path]`	Required

from harnest.skills import FilesystemSkillSource

source = FilesystemSkillSource(directories=...)

FilesystemSkillSource.list

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.

Parameters and example

Parameter	Type	Default
`context`	`SkillContext`	Required
`query`	`str \| None`	`None`
`cursor`	`str \| None`	`None`
`limit`	`int`	`50`

from harnest.skills import FilesystemSkillSource

source: FilesystemSkillSource
page = await source.list(context=...)

FilesystemSkillSource.load

async FilesystemSkillSource.load(skill_id: str, context: SkillContext, *, version: str | None = None) -> SkillDocument

Read one static manifest after validating its pinned version.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`context`	`SkillContext`	Required
`version`	`str \| None`	`None`

from harnest.skills import FilesystemSkillSource

source: FilesystemSkillSource
document = await source.load(skill_id=..., context=...)

FilesystemSkillSource.load_resource

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`path`	`str`	Required
`context`	`SkillContext`	Required
`version`	`str \| None`	`None`

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.

Example

from harnest.skills import FilesystemSkillSource

source: FilesystemSkillSource
value = source.descriptors

FilesystemSkillSource.routing_identity

Distinguish equal content owned by different agent directories.

Example

from harnest.skills import FilesystemSkillSource

source: FilesystemSkillSource
value = source.routing_identity

SkillAccess

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

SkillAccess(scope: SkillScope, active: Any) -> None

Parameters and example

Parameter	Type	Default
`scope`	`SkillScope`	Required
`active`	`Any`	Required

from harnest.skills import SkillAccess

access = SkillAccess(scope=..., active=...)

SkillAccess.list

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.

Parameters and example

Parameter	Type	Default
`source`	`str \| None`	`None`
`query`	`str \| None`	`None`
`cursor`	`str \| None`	`None`
`limit`	`int`	`50`

from harnest.skills import SkillAccess

access: SkillAccess
page = await access.list()

SkillAccess.load

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`source`	`str \| None`	`None`
`version`	`str \| None`	`None`

from harnest.skills import SkillAccess

access: SkillAccess
document = await access.load(skill_id=...)

SkillAccess.load_resource

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`path`	`str`	Required
`source`	`str \| None`	`None`
`version`	`str \| None`	`None`

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.

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`

Parameters and example

Parameter	Type	Default
`items`	`tuple[CatalogSkill, ...]`	Required
`next_cursors`	`Mapping[str, str]`	`...`
`truncated`	`bool`	`False`

from harnest.skills import SkillCatalogPage

page = SkillCatalogPage(items=...)

SkillCatalogPage.as_dict

SkillCatalogPage.as_dict() -> dict[str, Any]

Return a JSON-safe catalog without including instruction bodies.

Example

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.

Example

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.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.task

SkillContext.state

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

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.state

SkillContext.framework

Return the framework active for this invocation.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.framework

SkillContext.agent_name

Return the exact root or subagent currently requesting skills.

Example

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.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.parent_agent_name

SkillContext.depth

Return the managed subagent nesting depth.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.depth

SkillContext.invocation_id

Return the current invocation correlation identity.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.invocation_id

SkillContext.user_id

Return the authenticated runtime user identity.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.user_id

SkillContext.claims

Return verified non-secret authentication claims when available.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.claims

SkillContext.session_id

Return the framework-neutral session identity.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.session_id

SkillContext.metadata

Return immutable non-secret invocation metadata.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.metadata

SkillContext.credentials

Return private credential resolution without copying secret values.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.credentials

SkillContext.storage

Return invocation-scoped access to named application storage.

Example

from harnest.skills import SkillContext

context: SkillContext
value = context.storage

SkillContext.resource

SkillContext.resource(name: str, expected_type: type[Any] | None = None) -> Any

Resolve an explicitly exported application resource.

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`expected_type`	`type[Any] \| None`	`None`

from harnest.skills import SkillContext

context: SkillContext
result = context.resource(name=...)

SkillDescriptor

Bounded metadata that lets a model select a skill progressively.

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`	`—`

Parameters and example

Parameter	Type	Default
`id`	`str`	Required
`name`	`str`	Required
`description`	`str`	Required
`version`	`str`	Required

from harnest.skills import SkillDescriptor

descriptor = SkillDescriptor(id=..., name=..., description=..., version=...)

SkillDocument

One versioned instruction document returned by a skill source.

SkillDocument(descriptor: SkillDescriptor, instructions: str) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`descriptor`	`SkillDescriptor`	Required
`instructions`	`str`	Required

from harnest.skills import SkillDocument

document = SkillDocument(descriptor=..., instructions=...)

SkillError

Base error for invalid or unavailable skill operations.

Example

from harnest.skills import SkillError

try:
    ...
except SkillError as error:
    ...

SkillNotFoundError

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

Example

from harnest.skills import SkillNotFoundError

try:
    ...
except SkillNotFoundError as error:
    ...

SkillPage

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

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`

Parameters and example

Parameter	Type	Default
`items`	`tuple[SkillDescriptor, ...]`	Required
`next_cursor`	`str \| None`	`None`

from harnest.skills import SkillPage

page = SkillPage(items=...)

SkillRegistry

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

SkillRegistry(scopes: Mapping[str, SkillScope] | None = None) -> None

Parameters and example

Parameter	Type	Default
`scopes`	`Mapping[str, SkillScope] \| None`	`None`

from harnest.skills import SkillRegistry

registry = SkillRegistry()

SkillRegistry.agent_names

Return compiled identities for diagnostics without exposing sources.

Example

from harnest.skills import SkillRegistry

registry: SkillRegistry
value = registry.agent_names

SkillRegistry.scope

SkillRegistry.scope(agent_name: str) -> SkillScope

Return one immutable compiled scope for runtime-safe augmentation.

Parameters and example

Parameter	Type	Default
`agent_name`	`str`	Required

from harnest.skills import SkillRegistry

registry: SkillRegistry
scope = registry.scope(agent_name=...)

SkillRegistry.access

SkillRegistry.access(active: Any) -> 'SkillAccess'

Bind a registry view to one revocable invocation context.

Parameters and example

Parameter	Type	Default
`active`	`Any`	Required

from harnest.skills import SkillRegistry

registry: SkillRegistry
access = registry.access(active=...)

SkillResource

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

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`	`—`

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`version`	`str`	Required
`path`	`str`	Required
`content`	`str`	Required

from harnest.skills import SkillResource

resource = SkillResource(skill_id=..., version=..., path=..., content=...)

SkillResourceNotSupported

A source deliberately does not expose supporting resources.

Example

from harnest.skills import SkillResourceNotSupported

try:
    ...
except SkillResourceNotSupported as error:
    ...

SkillScope

Compose named sources for one compiled agent or subagent identity.

SkillScope(sources: Mapping[str, SkillSource] | None = None) -> None

Parameters and example

Parameter	Type	Default
`sources`	`Mapping[str, SkillSource] \| None`	`None`

from harnest.skills import SkillScope

scope = SkillScope()

SkillScope.source_names

Return stable source identities without exposing provider objects.

Example

from harnest.skills import SkillScope

scope: SkillScope
value = scope.source_names

SkillScope.routing_identity

Compare repeated compiler composition without equating remote clients.

Example

from harnest.skills import SkillScope

scope: SkillScope
value = scope.routing_identity

SkillScope.with_filesystem_directories

SkillScope.with_filesystem_directories(directories: Sequence[str | Path]) -> 'SkillScope'

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

Parameters and example

Parameter	Type	Default
`directories`	`Sequence[str \| Path]`	Required

from harnest.skills import SkillScope

scope: SkillScope
scope = scope.with_filesystem_directories(directories=...)

SkillScope.list

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.

Parameters and example

Parameter	Type	Default
`context`	`SkillContext`	Required
`source`	`str \| None`	`None`
`query`	`str \| None`	`None`
`cursor`	`str \| None`	`None`
`limit`	`int`	`50`

from harnest.skills import SkillScope

scope: SkillScope
page = await scope.list(context=...)

SkillScope.load

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`context`	`SkillContext`	Required
`source`	`str \| None`	`None`
`version`	`str \| None`	`None`

from harnest.skills import SkillScope

scope: SkillScope
document = await scope.load(skill_id=..., context=...)

SkillScope.load_resource

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`path`	`str`	Required
`context`	`SkillContext`	Required
`source`	`str \| None`	`None`
`version`	`str \| None`	`None`

from harnest.skills import SkillScope

scope: SkillScope
resource = await scope.load_resource(skill_id=..., path=..., context=...)

SkillScope.selected_source

SkillScope.selected_source(source: str | None = None) -> str

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

Parameters and example

Parameter	Type	Default
`source`	`str \| None`	`None`

from harnest.skills import SkillScope

scope: SkillScope
result = scope.selected_source()

SkillSelectionError

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

Example

from harnest.skills import SkillSelectionError

try:
    ...
except SkillSelectionError as error:
    ...

SkillSelectionFallback

Closed failure modes; ordinary discovery remains available by default.

SkillSelectionFallback(*values)

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

Example

from harnest.skills import SkillSelectionFallback

value = SkillSelectionFallback.DISCOVERY

SkillSource

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

SkillSource()

Example

from harnest.skills import SkillSource

class MySkillSource(SkillSource):
    ...

SkillSource.list

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.

Parameters and example

Parameter	Type	Default
`context`	`SkillContext`	Required
`query`	`str \| None`	`None`
`cursor`	`str \| None`	`None`
`limit`	`int`	`50`

from harnest.skills import SkillSource

source: SkillSource
page = await source.list(context=...)

SkillSource.load

async SkillSource.load(skill_id: str, context: SkillContext, *, version: str | None = None) -> SkillDocument

Load one authorized versioned instruction document.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`context`	`SkillContext`	Required
`version`	`str \| None`	`None`

from harnest.skills import SkillSource

source: SkillSource
document = await source.load(skill_id=..., context=...)

SkillSource.load_resource

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.

Parameters and example

Parameter	Type	Default
`skill_id`	`str`	Required
`path`	`str`	Required
`context`	`SkillContext`	Required
`version`	`str \| None`	`None`

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.

Example

from harnest.skills import SkillSourceExecutionError

try:
    ...
except SkillSourceExecutionError as error:
    ...

SkillValidationError

A source or skill value violates the portable contract.

Example

from harnest.skills import SkillValidationError

try:
    ...
except SkillValidationError as error:
    ...

​Exports

​CatalogSkill

​CatalogSkill.as_dict

​DecisionSkillSelector

​FilesystemSkillSource

​FilesystemSkillSource.list

​FilesystemSkillSource.load

​FilesystemSkillSource.load_resource

​FilesystemSkillSource.descriptors

​FilesystemSkillSource.routing_identity

​SkillAccess

​SkillAccess.list

​SkillAccess.load

​SkillAccess.load_resource

​SkillCatalogPage

​SkillCatalogPage.as_dict

​SkillContext

​SkillContext.task

​SkillContext.state

​SkillContext.framework

​SkillContext.agent_name

​SkillContext.parent_agent_name

​SkillContext.depth

​SkillContext.invocation_id

​SkillContext.user_id

​SkillContext.claims

​SkillContext.session_id

​SkillContext.metadata

​SkillContext.credentials

​SkillContext.storage

​SkillContext.resource

​SkillDescriptor

​SkillDocument

​SkillError

​SkillNotFoundError

​SkillPage

​SkillRegistry

​SkillRegistry.agent_names

​SkillRegistry.scope

​SkillRegistry.access

​SkillResource

​SkillResourceNotSupported

​SkillScope

​SkillScope.source_names

​SkillScope.routing_identity

​SkillScope.with_filesystem_directories

​SkillScope.list

​SkillScope.load

​SkillScope.load_resource

​SkillScope.selected_source

​SkillSelectionError

​SkillSelectionFallback

​SkillSource

​SkillSource.list

​SkillSource.load

​SkillSource.load_resource

​SkillSourceExecutionError

​SkillValidationError

Exports

CatalogSkill

CatalogSkill.as_dict

DecisionSkillSelector

FilesystemSkillSource

FilesystemSkillSource.list

FilesystemSkillSource.load

FilesystemSkillSource.load_resource

FilesystemSkillSource.descriptors

FilesystemSkillSource.routing_identity

SkillAccess

SkillAccess.list

SkillAccess.load

SkillAccess.load_resource

SkillCatalogPage

SkillCatalogPage.as_dict

SkillContext

SkillContext.task

SkillContext.state

SkillContext.framework

SkillContext.agent_name

SkillContext.parent_agent_name

SkillContext.depth

SkillContext.invocation_id

SkillContext.user_id

SkillContext.claims

SkillContext.session_id

SkillContext.metadata

SkillContext.credentials

SkillContext.storage

SkillContext.resource

SkillDescriptor

SkillDocument

SkillError

SkillNotFoundError

SkillPage

SkillRegistry

SkillRegistry.agent_names

SkillRegistry.scope

SkillRegistry.access

SkillResource

SkillResourceNotSupported

SkillScope

SkillScope.source_names

SkillScope.routing_identity

SkillScope.with_filesystem_directories

SkillScope.list

SkillScope.load

SkillScope.load_resource

SkillScope.selected_source

SkillSelectionError

SkillSelectionFallback

SkillSource

SkillSource.list

SkillSource.load

SkillSource.load_resource

SkillSourceExecutionError

SkillValidationError