bundled-skill-file-extraction

name	bundled-skill-file-extraction
description	Lazily extract referenced files for bundled skills so large prompts stay offline until needed.
metadata	{"author":"ychampion"}

SKILL: Bundled Skill File Extraction

Domain: command-surfaces
Trigger: Use whenever a bundled skill needs reference files extracted on demand while keeping startup fast. Source Pattern: Distilled from reviewed command-surface and listing-control patterns.

Core Method

When a bundled skill defines files, memoize an extraction promise and write each file under a secure directory (with O_NOFOLLOW / 0o700+ permissions). Cache the extraction path so the same directory can be reused across invocations, and wrap the skill prompt with Base directory for this skill: <dir> so the agent can Read/Grep as needed without bloating the inline instructions.

Key Rules

• Group requested files by parent directory when writing so mkdir/disk writes happen per subtree.
• Allocate per-process directories under the locked getBundledSkillsRoot() and avoid overwriting by using O_EXCL/SAFE_WRITE_FLAGS.
• Memoize the extraction promise (not just the result) so concurrent invocations await a single write.
• Prepend Base directory ... to the skill prompt only when the extraction succeeded; otherwise continue without the prefix to keep the skill usable.

Example Application

When packaging a bundled “project review” skill with large README snippets, add files entries for the README, let this method extract them lazily, and cite the base directory in the prompt so the agent can Read the files only when it actually runs the skill.

Anti-Patterns (What NOT to do)

• Don’t write the files directly during startup—delay until the first invocation, using memoized promises to avoid race conditions.
• Don’t forget to guard against traversal (resolveSkillFilePath) so bad relpaths cannot escape the extraction dir.