File Reference Skill

Name: File Reference Skill
Author: maxvaega

maxvaega/skillkit

5 installs
146 repo stars
Updated January 23, 2026
maxvaega/skillkit

Helps with ai & agent building tasks.

About

file-reference-skill is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted coding.

file-reference-skill
AI & Agent Building
AI-coding skill

File Reference Skill by the numbers

5 all-time installs (skills.sh)
Ranked #13,065 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/maxvaega/skillkit --skill file-reference-skill

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/maxvaega/skillkit/file-reference-skill.svg)](https://skillselion.com/skills/maxvaega/skillkit/file-reference-skill)

Installs	5
repo stars	★ 146
Last updated	January 23, 2026
Repository	maxvaega/skillkit ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

File Reference Skill

This skill demonstrates how to use supporting files (scripts, templates, documentation) within a skill directory.

Overview

This skill uses helper scripts and templates for data processing. All supporting files are accessible via relative paths from the skill's base directory.

Available Supporting Files

Scripts

scripts/data_processor.py - Main data processing script
scripts/validator.py - Input validation utilities
scripts/helper.sh - Shell helper script

Templates

templates/config.yaml - Configuration template
templates/report.md - Report generation template

Documentation

docs/usage.md - Detailed usage instructions
docs/examples.md - Example use cases

Usage

When this skill is invoked with arguments, it can access supporting files using the FilePathResolver:

from pathlib import Path
from skillkit.core.path_resolver import FilePathResolver

# Get the skill's base directory (injected by BaseDirectoryProcessor)
base_dir = Path("<base_directory_from_context>")

# Resolve supporting files securely
processor_script = FilePathResolver.resolve_path(base_dir, "scripts/data_processor.py")
config_template = FilePathResolver.resolve_path(base_dir, "templates/config.yaml")
usage_docs = FilePathResolver.resolve_path(base_dir, "docs/usage.md")

# Read file contents
with open(processor_script) as f:
    script_code = f.read()

Processing Arguments

The skill expects data file paths as arguments:

Example invocation: file-reference-skill data/input.csv data/output.csv

Processing steps: 1. Validate input using scripts/validator.py 2. Process data using scripts/data_processor.py 3. Generate report using templates/report.md 4. Output results to specified location

Security Notes

All file paths are validated to prevent directory traversal attacks
Symlinks are resolved and verified to stay within skill directory
Absolute paths and path traversal patterns (../) are blocked
Any security violation raises PathSecurityError with detailed logging

File Reference Skill - Examples

Example 1: Simple Data Processing

Process a CSV file using the skill's data processor:

from skillkit import SkillManager
from skillkit.core.path_resolver import FilePathResolver
from pathlib import Path

# Initialize skill manager
manager = SkillManager("./examples/skills")
manager.discover()

# Invoke skill
result = manager.invoke_skill(
    "file-reference-skill",
    "data/input.csv data/output.csv"
)

print(result)

Example 2: Accessing Supporting Scripts

Read and execute supporting scripts:

from pathlib import Path
from skillkit.core.path_resolver import FilePathResolver

# Get skill's base directory
skill = manager.get_skill("file-reference-skill")
base_dir = skill.base_directory

# Resolve script path securely
processor_path = FilePathResolver.resolve_path(
    base_dir,
    "scripts/data_processor.py"
)

# Read script content
with open(processor_path) as f:
    script_code = f.read()

print(f"Script location: {processor_path}")
print(f"Script length: {len(script_code)} bytes")

Example 3: Loading Configuration Template

Load and parse configuration template:

import yaml
from skillkit.core.path_resolver import FilePathResolver

# Resolve config template path
config_path = FilePathResolver.resolve_path(
    base_dir,
    "templates/config.yaml"
)

# Load configuration
with open(config_path) as f:
    config = yaml.safe_load(f)

print("Configuration:", config)

Example 4: Handling Security Violations

Demonstrate path traversal prevention:

from skillkit.core.path_resolver import FilePathResolver
from skillkit.core.exceptions import PathSecurityError

try:
    # Attempt path traversal (will be blocked)
    malicious_path = FilePathResolver.resolve_path(
        base_dir,
        "../../../etc/passwd"
    )
except PathSecurityError as e:
    print(f"Security violation blocked: {e}")
    # Expected output:
    # Security violation blocked: Path traversal attempt detected:
    # '../../../etc/passwd' resolves outside skill directory

Example 5: Validating Input Files

Use validator script to check input files:

import subprocess
from skillkit.core.path_resolver import FilePathResolver

# Resolve validator script
validator_path = FilePathResolver.resolve_path(
    base_dir,
    "scripts/validator.py"
)

# Import and use validator
import sys
sys.path.insert(0, str(validator_path.parent))
from validator import validate_csv_format

# Validate input file
is_valid = validate_csv_format("data/input.csv")
print(f"File is valid: {is_valid}")

Example 6: Generating Reports

Generate report using template:

from string import Template
from datetime import datetime
from skillkit.core.path_resolver import FilePathResolver

# Resolve report template
template_path = FilePathResolver.resolve_path(
    base_dir,
    "templates/report.md"
)

# Load template
with open(template_path) as f:
    template_content = f.read()

# Fill template with data
template = Template(template_content)
report = template.safe_substitute({
    'timestamp': datetime.now().isoformat(),
    'input_file': 'data/input.csv',
    'input_size': '1234',
    'format': 'CSV',
    'encoding': 'UTF-8',
    'start_time': '10:00:00',
    'end_time': '10:00:05',
    'duration': '5',
    'status': 'SUCCESS',
    'output_file': 'data/output.csv',
    'output_size': '1234',
    'record_count': '100',
    'error_count': '0',
    'validation_results': 'All checks passed',
    'processing_log': 'Processing completed successfully'
})

print(report)

Example 7: Shell Script Integration

Execute shell helper script:

import subprocess
from skillkit.core.path_resolver import FilePathResolver

# Resolve shell script
helper_path = FilePathResolver.resolve_path(
    base_dir,
    "scripts/helper.sh"
)

# Execute script
result = subprocess.run(
    ['bash', str(helper_path), 'check'],
    capture_output=True,
    text=True
)

print(result.stdout)

Example 8: Multiple File Access

Access multiple supporting files in one operation:

from skillkit.core.path_resolver import FilePathResolver

# List of files to access
file_paths = [
    "scripts/data_processor.py",
    "scripts/validator.py",
    "templates/config.yaml",
    "docs/usage.md"
]

# Resolve all paths securely
resolved_paths = {}
for rel_path in file_paths:
    try:
        abs_path = FilePathResolver.resolve_path(base_dir, rel_path)
        resolved_paths[rel_path] = abs_path
        print(f"✓ {rel_path} -> {abs_path}")
    except PathSecurityError as e:
        print(f"✗ {rel_path} -> BLOCKED ({e})")

print(f"\nSuccessfully resolved {len(resolved_paths)} paths")

Example 9: Error Handling Best Practices

Robust error handling when accessing supporting files:

from pathlib import Path
from skillkit.core.path_resolver import FilePathResolver
from skillkit.core.exceptions import PathSecurityError

def safe_load_supporting_file(base_dir: Path, rel_path: str) -> str:
    """Safely load supporting file with comprehensive error handling."""
    try:
        # Resolve path securely
        abs_path = FilePathResolver.resolve_path(base_dir, rel_path)

        # Read file content
        with open(abs_path, 'r', encoding='utf-8') as f:
            return f.read()

    except PathSecurityError as e:
        print(f"Security violation: {e}")
        raise
    except FileNotFoundError:
        print(f"File not found: {rel_path}")
        raise
    except PermissionError:
        print(f"Permission denied: {rel_path}")
        raise
    except UnicodeDecodeError:
        print(f"Invalid UTF-8 encoding: {rel_path}")
        raise
    except Exception as e:
        print(f"Unexpected error loading {rel_path}: {e}")
        raise

# Usage
try:
    content = safe_load_supporting_file(base_dir, "scripts/helper.py")
    print(f"Loaded {len(content)} bytes")
except Exception as e:
    print(f"Failed to load file: {e}")

Summary

These examples demonstrate:

Secure file path resolution using FilePathResolver
Accessing scripts, templates, and documentation
Handling security violations gracefully
Integration with Python and shell scripts
Best practices for error handling
Template-based report generation

File Reference Skill - Usage Guide

Overview

The file-reference-skill demonstrates how to structure a skill with supporting files (scripts, templates, documentation) and access them securely using the FilePathResolver.

Directory Structure

file-reference-skill/
├── SKILL.md                 # Main skill definition
├── scripts/                 # Processing scripts
│   ├── data_processor.py    # Main data processor
│   ├── validator.py         # Input validation
│   └── helper.sh            # Shell utilities
├── templates/               # Configuration and output templates
│   ├── config.yaml          # Configuration template
│   └── report.md            # Report generation template
└── docs/                    # Documentation
    ├── usage.md             # This file
    └── examples.md          # Example use cases

Using Supporting Files

From Python

from pathlib import Path
from skillkit.core.path_resolver import FilePathResolver

# Base directory is provided in the skill context
base_dir = Path("/path/to/skills/file-reference-skill")

# Resolve paths securely
processor_path = FilePathResolver.resolve_path(
    base_dir,
    "scripts/data_processor.py"
)

# Read file content
with open(processor_path) as f:
    script_code = f.read()

From Shell

# Get base directory from skill context
BASE_DIR="/path/to/skills/file-reference-skill"

# Use helper script
bash "$BASE_DIR/scripts/helper.sh" check

# Run data processor
python3 "$BASE_DIR/scripts/data_processor.py" input.csv output.csv

Security Features

The FilePathResolver ensures:

1. Path Traversal Prevention: Blocks attempts to access files outside skill directory 2. Symlink Validation: Resolves symlinks and verifies targets stay within base directory 3. Absolute Path Rejection: Prevents absolute path injection 4. Detailed Logging: All security violations logged at ERROR level

Valid Paths

# Allowed - relative path within skill directory
FilePathResolver.resolve_path(base_dir, "scripts/helper.py")
FilePathResolver.resolve_path(base_dir, "templates/config.yaml")
FilePathResolver.resolve_path(base_dir, "docs/usage.md")

Invalid Paths (Blocked)

# Blocked - directory traversal
FilePathResolver.resolve_path(base_dir, "../../etc/passwd")

# Blocked - absolute path
FilePathResolver.resolve_path(base_dir, "/etc/passwd")

# Blocked - symlink escape
# (if symlink target is outside base_dir)
FilePathResolver.resolve_path(base_dir, "malicious_link")

Example Workflow

1. Skill Invocation

   manager = SkillManager()
   manager.discover()

   result = manager.invoke_skill(
       "file-reference-skill",
       "input_data.csv output_data.csv"
   )

2. Skill Processing

Skill receives base directory in context
Script paths resolved using FilePathResolver
Scripts executed with validated paths
Results returned to caller

3. File Access

All file operations use resolved paths
Security violations raise PathSecurityError
Detailed error messages help debugging

Best Practices

1. Always use FilePathResolver for accessing supporting files 2. Use relative paths from skill base directory 3. Document file dependencies in SKILL.md 4. Test with various path patterns including edge cases 5. Handle PathSecurityError appropriately in your code

Troubleshooting

PathSecurityError

Problem: Attempting to access files outside skill directory

Solution: Use relative paths within skill directory only

FileNotFoundError

Problem: Resolved path doesn't exist

Solution: Verify file exists in skill directory structure

PermissionError

Problem: Cannot read resolved file

Solution: Check file permissions and ownership

"""Data processing script for file-reference-skill.

This script demonstrates how supporting files can be used within a skill.
"""

import sys
from pathlib import Path


def process_data(input_file: str, output_file: str) -> None:
    """Process data from input file and write to output file.

    Args:
        input_file: Path to input data file
        output_file: Path to output data file
    """
    print(f"Processing data from {input_file}")
    print(f"Output will be written to {output_file}")

    # Read input file
    try:
        with open(input_file, 'r') as f:
            data = f.read()
        print(f"Read {len(data)} bytes from input file")
    except FileNotFoundError:
        print(f"Error: Input file not found: {input_file}")
        sys.exit(1)

    # Process data (example: uppercase transformation)
    processed_data = data.upper()

    # Write output file
    with open(output_file, 'w') as f:
        f.write(processed_data)
    print(f"Wrote {len(processed_data)} bytes to output file")


def main() -> None:
    """Main entry point."""
    if len(sys.argv) != 3:
        print("Usage: data_processor.py <input_file> <output_file>")
        sys.exit(1)

    input_file = sys.argv[1]
    output_file = sys.argv[2]

    process_data(input_file, output_file)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Environment Variable Demonstration Script

This script demonstrates how skillkit automatically injects environment
variables into script execution context.

Injected Variables:
    - SKILL_NAME: Name of the skill
    - SKILL_BASE_DIR: Absolute path to skill directory
    - SKILL_VERSION: Version from skill metadata
    - SKILLKIT_VERSION: Current skillkit version

These variables can be used for:
    - Locating files relative to skill directory
    - Including skill context in logs
    - Version-specific behavior
    - Debugging and troubleshooting

Usage:
    This script is designed to be executed by skillkit's script executor.
    It reads JSON arguments from stdin and writes results to stdout.
"""

import json
import os
import sys
from pathlib import Path


def main():
    """Demonstrate environment variable access."""
    # Read arguments from stdin (standard skillkit pattern)
    try:
        args = json.load(sys.stdin)
    except json.JSONDecodeError:
        args = {}

    # Access injected environment variables
    skill_name = os.environ.get('SKILL_NAME', 'unknown')
    skill_base = os.environ.get('SKILL_BASE_DIR', 'unknown')
    skill_version = os.environ.get('SKILL_VERSION', '0.0.0')
    skillkit_version = os.environ.get('SKILLKIT_VERSION', 'unknown')

    # Prepare output
    output = {
        "message": "Environment variables successfully accessed!",
        "context": {
            "skill_name": skill_name,
            "skill_base_dir": skill_base,
            "skill_version": skill_version,
            "skillkit_version": skillkit_version
        },
        "arguments_received": args,
        "examples": {
            "relative_file_path": "Use SKILL_BASE_DIR to locate files",
            "logging": f"[{skill_name} v{skill_version}] Log message here",
            "file_resolution": str(Path(skill_base) / "data" / "config.json")
        }
    }

    # Print formatted output
    print("=" * 60)
    print(f"Skill: {skill_name} v{skill_version}")
    print(f"Directory: {skill_base}")
    print(f"Powered by: skillkit v{skillkit_version}")
    print("=" * 60)
    print()
    print("Environment Variables:")
    print(f"  SKILL_NAME        = {skill_name}")
    print(f"  SKILL_BASE_DIR    = {skill_base}")
    print(f"  SKILL_VERSION     = {skill_version}")
    print(f"  SKILLKIT_VERSION  = {skillkit_version}")
    print()
    print("Arguments Received:")
    print(f"  {json.dumps(args, indent=2)}")
    print()
    print("Example Use Cases:")
    print(f"  1. Locate skill files:")
    print(f"     config_path = Path(os.environ['SKILL_BASE_DIR']) / 'config.json'")
    print(f"     → {Path(skill_base) / 'config.json'}")
    print()
    print(f"  2. Contextual logging:")
    print(f"     logger.info(f'[{{os.environ[\"SKILL_NAME\"]}}] Processing...')")
    print(f"     → [{skill_name}] Processing...")
    print()
    print(f"  3. Version-specific behavior:")
    print(f"     if os.environ['SKILL_VERSION'] >= '2.0.0':")
    print(f"         use_new_api()")
    print()
    print("=" * 60)

    # Also output as JSON for programmatic use
    print()
    print("JSON Output:")
    print(json.dumps(output, indent=2))

    # Exit successfully
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/bin/bash
# Helper script for file-reference-skill

echo "File Reference Skill Helper Script"
echo "==================================="
echo ""
echo "This script demonstrates shell scripting support in skills."
echo ""
echo "Usage: ./helper.sh <command> [args...]"
echo ""

case "${1:-help}" in
    check)
        echo "Checking environment..."
        echo "Python version: $(python3 --version)"
        echo "Current directory: $(pwd)"
        echo "Script directory: $(dirname "$0")"
        ;;
    validate)
        if [ -z "$2" ]; then
            echo "Error: No file specified"
            exit 1
        fi
        echo "Validating file: $2"
        if [ -f "$2" ]; then
            echo "File exists: $2"
            echo "File size: $(wc -c < "$2") bytes"
        else
            echo "File not found: $2"
            exit 1
        fi
        ;;
    help|*)
        echo "Available commands:"
        echo "  check    - Check environment"
        echo "  validate <file> - Validate file exists"
        echo "  help     - Show this help message"
        ;;
esac

"""Input validation utilities for file-reference-skill."""

from pathlib import Path


def validate_file_path(file_path: str) -> bool:
    """Validate that a file path exists and is readable.

    Args:
        file_path: Path to validate

    Returns:
        True if valid, False otherwise
    """
    path = Path(file_path)

    if not path.exists():
        print(f"Error: File does not exist: {file_path}")
        return False

    if not path.is_file():
        print(f"Error: Path is not a file: {file_path}")
        return False

    try:
        with open(path, 'r') as f:
            f.read(1)
        return True
    except PermissionError:
        print(f"Error: Permission denied reading file: {file_path}")
        return False
    except Exception as e:
        print(f"Error: Cannot read file: {file_path} ({e})")
        return False


def validate_csv_format(file_path: str) -> bool:
    """Validate that a file is in CSV format.

    Args:
        file_path: Path to CSV file

    Returns:
        True if valid CSV, False otherwise
    """
    if not validate_file_path(file_path):
        return False

    # Check file extension
    if not file_path.endswith('.csv'):
        print(f"Warning: File does not have .csv extension: {file_path}")

    # Check for CSV content (basic validation)
    with open(file_path, 'r') as f:
        first_line = f.readline()
        if ',' not in first_line:
            print(f"Warning: File may not be valid CSV (no commas found): {file_path}")
            return False

    return True

# Configuration template for file-reference-skill

# Data processing settings
processing:
  input_format: csv
  output_format: csv
  encoding: utf-8
  delimiter: ","
  skip_header: false

# Validation settings
validation:
  check_encoding: true
  check_format: true
  max_file_size_mb: 100
  required_columns: []

# Output settings
output:
  include_timestamp: true
  compress: false
  create_backup: true

# Logging settings
logging:
  level: INFO
  format: "%(asctime)s - %(levelname)s - %(message)s"
  file: "processing.log"