feat(skills): expose assets and gated non-standard resources through the skill tool #162

New issue

Open

opened 2026-11-09 16:21:35 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-11-09 16:21:35 +00:00

Member

Metadata

Commit Message: feat(skills): expose assets and gated non-standard resources through the skill tool
Branch: feature/m1-skill-resource-manifest-and-assets

Background and context

ADR-2034 D-8 makes assets/ a first-class resource class alongside
references/, and makes every non-standard top-level folder privileged. The
current skill tool can read a named resource from the flat map, but it does not
build a resource manifest and has no read policy for non-standard folders. The
model therefore cannot discover assets and cannot tell which paths are gated.

Current behavior

Activating a skill returns only instructions; there is no bundled-resource
manifest.
A resource read works for any path in the flat map, including non-standard
folders, with no safety check.
Assets are not distinguished from references.

Expected behavior

On activation, return instructions plus a bundled-resource manifest grouped
by class: references/, assets/, and scripts/. Non-standard entries are
listed only when the D-9 gate is active.
Resource reads work for assets/ exactly as for references/: text is
decoded, binary content is returned as base64, and the existing
[SKILL_RESOURCE_READ] envelope plus ADR-2033 pagination are preserved.
Reading or listing a non-standard resource requires the D-9 double-safety
gate: global safety false AND skill safety false. Otherwise it fails with an
ExecutionError naming both states and the requested path.
Reading a scripts/ source file remains allowed in every mode; execution is
not part of this issue.
references/, assets/, and root-level files remain readable in every mode.

Acceptance criteria

Activation output lists every references/, assets/, and scripts/ entry
in the manifest; assets/ entries are visibly distinguishable.
A text asset read returns its decoded content; a binary asset read returns its
base64 representation without crashing.
A non-standard resource read is refused when global safety is true or skill
safety is true, and succeeds only when both are false.
A non-standard path never appears in the activation manifest while the gate is
inactive.
A script source read is allowed in safe mode.
Existing skill activation, pagination, and reference-read scenarios remain
green.
New Behave scenarios cover the manifest and the asset/non-standard read
matrix; a Robot integration scenario exercises an asset read and a refused
non-standard read.
Coverage remains >= 97% via nox -s coverage_report.

Supporting information

ADR-2034 D-8 (taxonomy), D-9 (double-safety gate), D-10 (tool contract)
Agent Skills specification: https://agentskills.io/specification
Module: cleveractors.agents.tool.ToolAgent._skill_tool,
cleveractors.agents.llm_tools
Existing tests: features/agent_skills.feature,
robot/agent_skills.robot

Subtasks

Build the class-grouped bundled-resource manifest
Add gated non-standard read/list handling
Return assets with decoded text or base64 content as appropriate
Update the skill tool schema description for assets and gated paths
Tests (Behave): manifest, text/binary assets, non-standard gate matrix
Tests (Robot): asset read and refused non-standard read end to end
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in
Metadata exactly.
The commit is pushed to the branch matching Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged.

## Metadata - **Commit Message**: `feat(skills): expose assets and gated non-standard resources through the skill tool` - **Branch**: `feature/m1-skill-resource-manifest-and-assets` ## Background and context ADR-2034 D-8 makes `assets/` a first-class resource class alongside `references/`, and makes every non-standard top-level folder privileged. The current `skill` tool can read a named resource from the flat map, but it does not build a resource manifest and has no read policy for non-standard folders. The model therefore cannot discover assets and cannot tell which paths are gated. ## Current behavior - Activating a skill returns only `instructions`; there is no bundled-resource manifest. - A resource read works for any path in the flat map, including non-standard folders, with no safety check. - Assets are not distinguished from references. ## Expected behavior - On activation, return `instructions` plus a bundled-resource manifest grouped by class: `references/`, `assets/`, and `scripts/`. Non-standard entries are listed only when the D-9 gate is active. - Resource reads work for `assets/` exactly as for `references/`: text is decoded, binary content is returned as base64, and the existing `[SKILL_RESOURCE_READ]` envelope plus ADR-2033 pagination are preserved. - Reading or listing a non-standard resource requires the D-9 double-safety gate: global safety false AND skill safety false. Otherwise it fails with an `ExecutionError` naming both states and the requested path. - Reading a `scripts/` source file remains allowed in every mode; execution is not part of this issue. - `references/`, `assets/`, and root-level files remain readable in every mode. ## Acceptance criteria - Activation output lists every `references/`, `assets/`, and `scripts/` entry in the manifest; `assets/` entries are visibly distinguishable. - A text asset read returns its decoded content; a binary asset read returns its base64 representation without crashing. - A non-standard resource read is refused when global safety is true or skill safety is true, and succeeds only when both are false. - A non-standard path never appears in the activation manifest while the gate is inactive. - A script source read is allowed in safe mode. - Existing skill activation, pagination, and reference-read scenarios remain green. - New Behave scenarios cover the manifest and the asset/non-standard read matrix; a Robot integration scenario exercises an asset read and a refused non-standard read. - Coverage remains >= 97% via `nox -s coverage_report`. ## Supporting information - ADR-2034 D-8 (taxonomy), D-9 (double-safety gate), D-10 (tool contract) - Agent Skills specification: https://agentskills.io/specification - Module: `cleveractors.agents.tool.ToolAgent._skill_tool`, `cleveractors.agents.llm_tools` - Existing tests: `features/agent_skills.feature`, `robot/agent_skills.robot` ## Subtasks - [ ] Build the class-grouped bundled-resource manifest - [ ] Add gated non-standard read/list handling - [ ] Return assets with decoded text or base64 content as appropriate - [ ] Update the `skill` tool schema description for assets and gated paths - [ ] Tests (Behave): manifest, text/binary assets, non-standard gate matrix - [ ] Tests (Robot): asset read and refused non-standard read end to end - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching Branch in Metadata exactly. - The commit is submitted as a pull request to `master`, reviewed, and merged.

Rows
Columns