file-reference-skill_skill

Overview

This skill demonstrates secure file reference resolution and how to safely use supporting files (scripts, templates, documentation) bundled with a skill. It shows a clear pattern for resolving, validating, and reading relative files from the skill base directory while preventing directory traversal and other path exploits. The goal is safe, reproducible access to helper scripts and templates during runtime.

How this skill works

The skill uses a FilePathResolver to convert relative supporting-file paths into validated absolute paths inside the skill base directory. It resolves symlinks, rejects absolute paths and traversal patterns like ../, and raises a PathSecurityError when a check fails. Typical workflow: resolve helper scripts and templates, run input validation, execute processing logic, and generate output using templates and docs.

When to use it

• When a skill needs to load bundled scripts, templates, or docs at runtime.
• When you must enforce strict security on file references to avoid directory traversal.
• When multiple supporting files (validators, processors, templates) live in the skill directory.
• When you want reproducible skill behavior by reading versioned files packaged with the skill.
• When you need to audit or log file resolution steps for compliance or debugging.

Best practices

• Always pass a validated skill base directory from the execution context rather than constructing paths dynamically.
• Use the provided resolver API to open files; do not concatenate raw user input into paths.
• Keep executable code (scripts) and non-executable assets (templates/docs) organized in distinct subfolders.
• Log resolution steps and failure reasons at a debug or audit level for traceability.
• Fail fast on any PathSecurityError and present a clear error message to the caller.

Example use cases

• Validate incoming data file paths using the bundled validator before processing.
• Resolve and execute a packaged data_processor.py script to transform CSV inputs to outputs.
• Generate reports by rendering templates/report.md with runtime data, using templates/config.yaml for settings.
• Ship skills that rely on offline helper scripts while ensuring those helpers cannot be overridden by path tricks.
• Include detailed usage docs and examples inside docs/ for operators to follow secure invocation steps.