Epic: Agent Skills — Full Resource Support and Safe Execution #160

New issue

Open

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

CoreRasurae commented

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

Member

Background and context

ADR-2034 (Skill Package Support) has been revised with decisions D-8, D-9 and
D-10. The original implementation can resolve and validate a skill package and
read generic files from its resources mapping, but it does not fully support
the remaining Agent Skills directory model: assets/ is not surfaced, scripts/
cannot be executed, arbitrary additional folders have no access policy, and a
skill package has no skill-local safety switch.

The design record is docs/adr/ADR-2034-skill-package-support.md (revision
2026-11-09). This Epic delivers the implementation, the matching specification
updates, and the directory-packing tooling required to author such skills.

Current behavior

resources accepts any relative path, but the loading path only describes
references/-style reads.
assets/ entries are not included in the activation manifest and are not
treated as a first-class resource class.
scripts/ entries can be read as text but there is no execution action.
A non-standard top-level folder has no read or execution policy.
Skill packages have no skill-local safe_mode; only the agent/host safety
switches exist.

Expected behavior

The Skill Package Schema carries an optional safe_mode boolean, default
true; safe_mode: false is part of the content-addressed identity and is
the only representation that appears in canonical content.
Resource paths are classified as references/, assets/, scripts/,
non-standard folders, or root files, following ADR-2034 D-8.
references/, assets/, and root-level files are readable in every mode.
Scripts are readable for inspection in every mode.
Script execution and any access to a non-standard folder require the
double-safety gate: global safety false AND skill safety false. The global
safety state follows the existing effective unsafe grant used for tool
dispatch.
Discovery/activation exposes a bundled-resource manifest so assets and
scripts are discoverable by the model.
A directory-to-pkg_skl_ packer preserves references/, assets/,
scripts/, and non-standard folders, and emits safe_mode only when false.

Acceptance criteria

A skill package without safe_mode behaves exactly as today and validates
successfully; a non-boolean safe_mode is rejected with a validation error.
A skill package with safe_mode: false has a different Package ID from the
same package with the field omitted.
Resource classification and the double-safety gate match ADR-2034 D-8–D-10.
Assets can be discovered and read (text decoded, binary returned as base64).
Script execution is impossible when either global safety or skill safety is
true, and is possible only when both are false and the agent already has
the existing command-execution capability enabled.
Non-standard folders cannot be read or executed unless both safety switches
are false.
The specification and packaging tooling are updated consistently.
All child issues are closed with their Definition of Done satisfied.

Supporting information

ADR: docs/adr/ADR-2034-skill-package-support.md (D-8, D-9, D-10)
Agent Skills specification: https://agentskills.io/specification
Package Registry Standard: docs/actor-registry-standard.md §16.1/§16.3
Actor Configuration Standard: docs/index.md §4.4
Existing implementation modules: cleveractors.agents.skill_schema,
cleveractors.agents.skills, cleveractors.agents.llm_tools,
cleveractors.agents.tool, cleveractors.agents.llm
Security posture precedent: ADR-2030 D-1, ADR-2035 D-5 (safe by default,
unsafe only by explicit opt-in)

Subtasks

Add skill-local safe_mode and resource classification to the Skill schema
Expose assets and gated non-standard resources through the skill tool
Execute skill scripts behind the double-safety gate
Document the skill schema, resource taxonomy, and execution gate
Add directory-to-package skill packing support

Definition of Done

This Epic is complete when:

All subtasks above are completed and checked off.
All child issues are closed and their Definition of Done criteria are met.
ADR-2034 D-8–D-10 are implemented and covered by BDD and Robot tests.
The Package Registry Standard and Actor Configuration Standard document the
new schema fields, resource classes, and execution gate.
A stakeholder can demonstrate an agent loading a skill that contains
references, assets, a script, and a non-standard folder; the script refuses to
run unless both safety switches are false, then runs successfully, and the
non-standard folder is inaccessible until the same gate is satisfied.
nox is green on the completed work.

## Background and context ADR-2034 (Skill Package Support) has been revised with decisions D-8, D-9 and D-10. The original implementation can resolve and validate a skill package and read generic files from its `resources` mapping, but it does not fully support the remaining Agent Skills directory model: `assets/` is not surfaced, `scripts/` cannot be executed, arbitrary additional folders have no access policy, and a skill package has no skill-local safety switch. The design record is `docs/adr/ADR-2034-skill-package-support.md` (revision 2026-11-09). This Epic delivers the implementation, the matching specification updates, and the directory-packing tooling required to author such skills. ## Current behavior - `resources` accepts any relative path, but the loading path only describes `references/`-style reads. - `assets/` entries are not included in the activation manifest and are not treated as a first-class resource class. - `scripts/` entries can be read as text but there is no execution action. - A non-standard top-level folder has no read or execution policy. - Skill packages have no skill-local `safe_mode`; only the agent/host safety switches exist. ## Expected behavior - The Skill Package Schema carries an optional `safe_mode` boolean, default `true`; `safe_mode: false` is part of the content-addressed identity and is the only representation that appears in canonical content. - Resource paths are classified as `references/`, `assets/`, `scripts/`, non-standard folders, or root files, following ADR-2034 D-8. - `references/`, `assets/`, and root-level files are readable in every mode. Scripts are readable for inspection in every mode. - Script execution and any access to a non-standard folder require the double-safety gate: global safety false AND skill safety false. The global safety state follows the existing effective unsafe grant used for tool dispatch. - Discovery/activation exposes a bundled-resource manifest so assets and scripts are discoverable by the model. - A directory-to-`pkg_skl_` packer preserves `references/`, `assets/`, `scripts/`, and non-standard folders, and emits `safe_mode` only when false. ## Acceptance criteria - A skill package without `safe_mode` behaves exactly as today and validates successfully; a non-boolean `safe_mode` is rejected with a validation error. - A skill package with `safe_mode: false` has a different Package ID from the same package with the field omitted. - Resource classification and the double-safety gate match ADR-2034 D-8–D-10. - Assets can be discovered and read (text decoded, binary returned as base64). - Script execution is impossible when either global safety or skill safety is `true`, and is possible only when both are `false` and the agent already has the existing command-execution capability enabled. - Non-standard folders cannot be read or executed unless both safety switches are `false`. - The specification and packaging tooling are updated consistently. - All child issues are closed with their Definition of Done satisfied. ## Supporting information - ADR: `docs/adr/ADR-2034-skill-package-support.md` (D-8, D-9, D-10) - Agent Skills specification: https://agentskills.io/specification - Package Registry Standard: `docs/actor-registry-standard.md` §16.1/§16.3 - Actor Configuration Standard: `docs/index.md` §4.4 - Existing implementation modules: `cleveractors.agents.skill_schema`, `cleveractors.agents.skills`, `cleveractors.agents.llm_tools`, `cleveractors.agents.tool`, `cleveractors.agents.llm` - Security posture precedent: ADR-2030 D-1, ADR-2035 D-5 (safe by default, unsafe only by explicit opt-in) ## Subtasks - [ ] Add skill-local `safe_mode` and resource classification to the Skill schema - [ ] Expose assets and gated non-standard resources through the skill tool - [ ] Execute skill scripts behind the double-safety gate - [ ] Document the skill schema, resource taxonomy, and execution gate - [ ] Add directory-to-package skill packing support ## Definition of Done This Epic is complete when: - All subtasks above are completed and checked off. - All child issues are closed and their Definition of Done criteria are met. - ADR-2034 D-8–D-10 are implemented and covered by BDD and Robot tests. - The Package Registry Standard and Actor Configuration Standard document the new schema fields, resource classes, and execution gate. - A stakeholder can demonstrate an agent loading a skill that contains references, assets, a script, and a non-standard folder; the script refuses to run unless both safety switches are false, then runs successfully, and the non-standard folder is inaccessible until the same gate is satisfied. - `nox` is green on the completed work.

Rows
Columns