Best practices for bundling scripts in skills including error handling, constants documentation, and execution patterns. Use when creating script-enabled skills.
Provides guidelines for bundling executable scripts in skills with proper error handling, documentation, and idempotent patterns. Use when creating script-enabled skills to ensure reliability and maintainability.
/plugin marketplace add mgd34msu/goodvibes-plugin/plugin install goodvibes@goodvibes-marketThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Guidelines for bundling executable scripts in skills.
Bundle scripts when:
Always handle errors explicitly rather than punting to Claude:
# Good: Handle errors explicitly
def process(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"Creating {path}")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
print(f"ERROR: Cannot access {path} - check permissions")
return None
# Bad: Let errors propagate unexpectedly
def process(path):
with open(path) as f:
return f.read() # Will crash on missing file
Every magic number needs rationale:
# Good: Document constants
TIMEOUT = 30 # HTTP requests typically complete in 30s
MAX_RETRIES = 3 # Most failures resolve by second retry
BATCH_SIZE = 100 # Balance between memory and API calls
# Bad: Magic numbers
TIMEOUT = 47 # Why 47?
MAX_RETRIES = 3 # Why 3?
Be explicit about how scripts should be used:
Execute the script:
Run `scripts/analyze.py` to extract form fields from the PDF.
Read as reference:
See `scripts/analyze.py` for the extraction algorithm (do not run directly).
skill-name/
SKILL.md
scripts/
analyze.py # Main entry point
validate.py # Validation utilities
helpers/ # Shared utilities
formatting.py
parsing.py
Always list dependencies explicitly:
## Requirements
Before running scripts:
```bash
pip install pdfplumber python-docx
Or with the provided requirements file:
pip install -r scripts/requirements.txt
## Exit Codes
Use consistent exit codes:
```python
import sys
EXIT_SUCCESS = 0
EXIT_INVALID_INPUT = 1
EXIT_FILE_NOT_FOUND = 2
EXIT_PERMISSION_ERROR = 3
def main():
if not validate_input():
sys.exit(EXIT_INVALID_INPUT)
# ... process ...
sys.exit(EXIT_SUCCESS)
Make output parseable:
# Good: Structured output
import json
result = {
"status": "success",
"files_processed": 5,
"errors": []
}
print(json.dumps(result))
# Bad: Unstructured output
print("Done! Processed 5 files with no errors.")
Scripts should be safe to run multiple times:
def ensure_directory(path):
"""Create directory if it doesn't exist (idempotent)."""
os.makedirs(path, exist_ok=True)
def write_if_changed(path, content):
"""Only write if content differs (idempotent)."""
if os.path.exists(path):
with open(path) as f:
if f.read() == content:
return False # No change needed
with open(path, 'w') as f:
f.write(content)
return True
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.