Motivation
Text skills currently expose special-purpose operations such as read_file and run_script. That gives text skills a second filesystem and execution abstraction, duplicates capabilities already owned by ShellTools, and makes their behavior more complicated than necessary.
Text skills should have the same basic object shape as other skills while remaining simple data-driven packages.
Proposed model
A text skill directory becomes a skill object with:
ShellTools as its execution and filesystem dependency- the contents of
SKILL.md as the skill class docstring/documentation
- a list of the files belonging to the skill
The text-skill implementation should not define its own read_file, run_script, or equivalent filesystem/process methods. Any file access or script execution should go through the injected ShellTools dependency and its existing policy, working-directory, streaming, and activity behavior.
Conceptually:
class GeneratedTextSkill(Skill):
\"\"\"Contents of SKILL.md.\"\"\"
shell: ShellTools
files: list[SkillFile]The exact generated/runtime class mechanism is an implementation detail; the important contract is that documentation, dependencies, and packaged files are represented directly rather than through a parallel tool API.
Acceptance criteria
- loading a text skill produces a normal skill object
- the skill documentation presented to the agent comes from
SKILL.md and is represented as the class docstring
- the skill exposes an explicit list of its packaged files with stable paths relative to the skill root
- the skill depends on/injects
ShellTools
- text skills no longer expose bespoke
read_file, run_script, or equivalent helper methods
- file reads and script execution use
ShellTools and inherit its safety boundaries and event behavior
- reload reconstructs the documentation and file list from current disk contents
- tests cover documentation, file discovery, ShellTools injection, reload, and removal of the legacy helper surface
- migration and compatibility behavior for existing text skills are documented
Related to the skill-loading work in #127, but intentionally tracked separately.
Motivation
Text skills currently expose special-purpose operations such as
read_fileandrun_script. That gives text skills a second filesystem and execution abstraction, duplicates capabilities already owned byShellTools, and makes their behavior more complicated than necessary.Text skills should have the same basic object shape as other skills while remaining simple data-driven packages.
Proposed model
A text skill directory becomes a skill object with:
ShellToolsas its execution and filesystem dependencySKILL.mdas the skill class docstring/documentationThe text-skill implementation should not define its own
read_file,run_script, or equivalent filesystem/process methods. Any file access or script execution should go through the injectedShellToolsdependency and its existing policy, working-directory, streaming, and activity behavior.Conceptually:
The exact generated/runtime class mechanism is an implementation detail; the important contract is that documentation, dependencies, and packaged files are represented directly rather than through a parallel tool API.
Acceptance criteria
SKILL.mdand is represented as the class docstringShellToolsread_file,run_script, or equivalent helper methodsShellToolsand inherit its safety boundaries and event behaviorRelated to the skill-loading work in #127, but intentionally tracked separately.