feat(skills): pack assets, scripts, non-standard folders, and safe_mode into skill packages #165

New issue

Open

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

CoreRasurae commented

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

Member

Metadata

Commit Message: feat(skills): pack assets, scripts, non-standard folders, and safe_mode into skill packages
Branch: feature/m1-skill-directory-packing

Background and context

ADR-2034 D-1/D-2 define a skill package as one content-addressed YAML mapping,
and D-6 identified directory-to-package packing as required follow-up tooling.
The revision adds assets, scripts, non-standard folders, and the skill-local
safe_mode field. Today there is no pack_skill_directory utility, so an
authorskills.io-style directory cannot be published as a pkg_skl_ package
without hand-writing the mapping.

Current behavior

No packer exists in the repository.
local: skill references require a pre-built single .yaml/.yml file.
There is no deterministic rule for including assets, scripts, or non-standard
folders in a package, and no rule for emitting safe_mode.

Expected behavior

Add a documented pack_skill_directory utility (or an equivalent
LocalPackageStore extension) that reads an on-disk skill directory and
produces a Skill Package mapping.
Preserve references/, assets/, scripts/, and non-standard folders
recursively; normalize keys to relative POSIX paths with no ./..
segments or leading slash.
Store valid UTF-8 files verbatim with encoding: utf-8; store non-UTF-8 files
as base64 with encoding: base64.
Parse SKILL.md frontmatter into the schema fields and the body into
instructions.
Emit safe_mode only when it is explicitly false; omit it when true so the
canonical default and existing Package IDs are preserved.
Validate the produced mapping through the existing SkillValidator and
compute the Package ID through the existing canonicalizer.
Fail with a clear error for missing SKILL.md, invalid frontmatter, a name
that does not match the directory name, invalid resource paths, or invalid
base64/UTF-8 classification.

Acceptance criteria

Packing a directory with SKILL.md, references/, assets/, scripts/, and
a non-standard folder produces a mapping that validates successfully.
Packing the same directory twice produces the same pkg_skl_ Package ID.
Text resources round-trip unchanged; binary resources round-trip through
base64.
A skill with no safe_mode in its source produces a mapping without the field;
an explicit safe_mode: false is preserved and changes the Package ID.
The packer rejects a directory whose SKILL.md name does not match the
directory name.
New Behave scenarios cover round-trip, determinism, binary assets, and the
safe_mode emission rule; a Robot integration scenario publishes a packed
skill through a local: or mocked registry reference and loads it.
Coverage remains >= 97% via nox -s coverage_report.

Supporting information

ADR-2034 D-1, D-2, D-3, D-6, D-8, D-9
Agent Skills specification: https://agentskills.io/specification
Package Registry Standard §16 and §6 (canonicalization)
Modules: cleveractors.agents.skill_schema,
cleveractors.registry.local_store, cleveractors.registry.canonical

Subtasks

Implement pack_skill_directory with frontmatter/body parsing
Implement recursive resource collection and POSIX path normalization
Implement UTF-8 vs base64 classification and safe_mode emission rules
Validate the packed mapping and compute its Package ID
Tests (Behave): round-trip, determinism, binary assets, safe_mode rule
Tests (Robot): pack and load a skill 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): pack assets, scripts, non-standard folders, and safe_mode into skill packages` - **Branch**: `feature/m1-skill-directory-packing` ## Background and context ADR-2034 D-1/D-2 define a skill package as one content-addressed YAML mapping, and D-6 identified directory-to-package packing as required follow-up tooling. The revision adds assets, scripts, non-standard folders, and the skill-local `safe_mode` field. Today there is no `pack_skill_directory` utility, so an authorskills.io-style directory cannot be published as a `pkg_skl_` package without hand-writing the mapping. ## Current behavior - No packer exists in the repository. - `local:` skill references require a pre-built single `.yaml`/`.yml` file. - There is no deterministic rule for including assets, scripts, or non-standard folders in a package, and no rule for emitting `safe_mode`. ## Expected behavior - Add a documented `pack_skill_directory` utility (or an equivalent `LocalPackageStore` extension) that reads an on-disk skill directory and produces a Skill Package mapping. - Preserve `references/`, `assets/`, `scripts/`, and non-standard folders recursively; normalize keys to relative POSIX paths with no `.`/`..` segments or leading slash. - Store valid UTF-8 files verbatim with `encoding: utf-8`; store non-UTF-8 files as base64 with `encoding: base64`. - Parse `SKILL.md` frontmatter into the schema fields and the body into `instructions`. - Emit `safe_mode` only when it is explicitly `false`; omit it when true so the canonical default and existing Package IDs are preserved. - Validate the produced mapping through the existing `SkillValidator` and compute the Package ID through the existing canonicalizer. - Fail with a clear error for missing `SKILL.md`, invalid frontmatter, a name that does not match the directory name, invalid resource paths, or invalid base64/UTF-8 classification. ## Acceptance criteria - Packing a directory with `SKILL.md`, `references/`, `assets/`, `scripts/`, and a non-standard folder produces a mapping that validates successfully. - Packing the same directory twice produces the same `pkg_skl_` Package ID. - Text resources round-trip unchanged; binary resources round-trip through base64. - A skill with no `safe_mode` in its source produces a mapping without the field; an explicit `safe_mode: false` is preserved and changes the Package ID. - The packer rejects a directory whose `SKILL.md` name does not match the directory name. - New Behave scenarios cover round-trip, determinism, binary assets, and the `safe_mode` emission rule; a Robot integration scenario publishes a packed skill through a `local:` or mocked registry reference and loads it. - Coverage remains >= 97% via `nox -s coverage_report`. ## Supporting information - ADR-2034 D-1, D-2, D-3, D-6, D-8, D-9 - Agent Skills specification: https://agentskills.io/specification - Package Registry Standard §16 and §6 (canonicalization) - Modules: `cleveractors.agents.skill_schema`, `cleveractors.registry.local_store`, `cleveractors.registry.canonical` ## Subtasks - [ ] Implement `pack_skill_directory` with frontmatter/body parsing - [ ] Implement recursive resource collection and POSIX path normalization - [ ] Implement UTF-8 vs base64 classification and safe_mode emission rules - [ ] Validate the packed mapping and compute its Package ID - [ ] Tests (Behave): round-trip, determinism, binary assets, safe_mode rule - [ ] Tests (Robot): pack and load a skill 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.

CoreRasurae added this to the v2.1.0 milestone

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

CoreRasurae added the

labels

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

CoreRasurae added a new dependency