176 lines
4.3 KiB
Markdown
176 lines
4.3 KiB
Markdown
<when_to_use_scripts>
|
|
Even if Claude could write a script, pre-made scripts offer advantages:
|
|
- More reliable than generated code
|
|
- Save tokens (no need to include code in context)
|
|
- Save time (no code generation required)
|
|
- Ensure consistency across uses
|
|
|
|
<execution_vs_reference>
|
|
Make clear whether Claude should:
|
|
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
|
|
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the extraction algorithm"
|
|
|
|
For most utility scripts, execution is preferred.
|
|
</execution_vs_reference>
|
|
|
|
<how_scripts_work>
|
|
When Claude executes a script via bash:
|
|
1. Script code never enters context window
|
|
2. Only script output consumes tokens
|
|
3. Far more efficient than having Claude generate equivalent code
|
|
</how_scripts_work>
|
|
</when_to_use_scripts>
|
|
|
|
<file_organization>
|
|
<scripts_directory>
|
|
**Best practice**: Place all executable scripts in a `scripts/` subdirectory within the skill folder.
|
|
|
|
```
|
|
skill-name/
|
|
├── SKILL.md
|
|
├── scripts/
|
|
│ ├── main_utility.py
|
|
│ ├── helper_script.py
|
|
│ └── validator.py
|
|
└── references/
|
|
└── api-docs.md
|
|
```
|
|
|
|
**Benefits**:
|
|
- Keeps skill root clean and organized
|
|
- Clear separation between documentation and executable code
|
|
- Consistent pattern across all skills
|
|
- Easy to reference: `python scripts/script_name.py`
|
|
|
|
**Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
|
|
|
|
```bash
|
|
python ~/.claude/skills/skill-name/scripts/analyze.py input.har
|
|
```
|
|
</scripts_directory>
|
|
</file_organization>
|
|
|
|
<utility_scripts_pattern>
|
|
<example>
|
|
## Utility scripts
|
|
|
|
**analyze_form.py**: Extract all form fields from PDF
|
|
|
|
```bash
|
|
python scripts/analyze_form.py input.pdf > fields.json
|
|
```
|
|
|
|
Output format:
|
|
```json
|
|
{
|
|
"field_name": { "type": "text", "x": 100, "y": 200 },
|
|
"signature": { "type": "sig", "x": 150, "y": 500 }
|
|
}
|
|
```
|
|
|
|
**validate_boxes.py**: Check for overlapping bounding boxes
|
|
|
|
```bash
|
|
python scripts/validate_boxes.py fields.json
|
|
# Returns: "OK" or lists conflicts
|
|
```
|
|
|
|
**fill_form.py**: Apply field values to PDF
|
|
|
|
```bash
|
|
python scripts/fill_form.py input.pdf fields.json output.pdf
|
|
```
|
|
</example>
|
|
</utility_scripts_pattern>
|
|
|
|
<solve_dont_punt>
|
|
Handle error conditions rather than punting to Claude.
|
|
|
|
<example type="good">
|
|
```python
|
|
def process_file(path):
|
|
"""Process a file, creating it if it doesn't exist."""
|
|
try:
|
|
with open(path) as f:
|
|
return f.read()
|
|
except FileNotFoundError:
|
|
print(f"File {path} not found, creating default")
|
|
with open(path, 'w') as f:
|
|
f.write('')
|
|
return ''
|
|
except PermissionError:
|
|
print(f"Cannot access {path}, using default")
|
|
return ''
|
|
```
|
|
</example>
|
|
|
|
<example type="bad">
|
|
```python
|
|
def process_file(path):
|
|
# Just fail and let Claude figure it out
|
|
return open(path).read()
|
|
```
|
|
</example>
|
|
|
|
<configuration_values>
|
|
Document configuration parameters to avoid "voodoo constants":
|
|
|
|
<example type="good">
|
|
```python
|
|
# HTTP requests typically complete within 30 seconds
|
|
REQUEST_TIMEOUT = 30
|
|
|
|
# Three retries balances reliability vs speed
|
|
MAX_RETRIES = 3
|
|
```
|
|
</example>
|
|
|
|
<example type="bad">
|
|
```python
|
|
TIMEOUT = 47 # Why 47?
|
|
RETRIES = 5 # Why 5?
|
|
```
|
|
</example>
|
|
</configuration_values>
|
|
</solve_dont_punt>
|
|
|
|
<package_dependencies>
|
|
<runtime_constraints>
|
|
Skills run in code execution environment with platform-specific limitations:
|
|
- **claude.ai**: Can install packages from npm and PyPI
|
|
- **Anthropic API**: No network access and no runtime package installation
|
|
</runtime_constraints>
|
|
|
|
<guidance>
|
|
List required packages in your SKILL.md and verify they're available.
|
|
|
|
<example type="good">
|
|
Install required package: `pip install pypdf`
|
|
|
|
Then use it:
|
|
|
|
```python
|
|
from pypdf import PdfReader
|
|
reader = PdfReader("file.pdf")
|
|
```
|
|
</example>
|
|
|
|
<example type="bad">
|
|
"Use the pdf library to process the file."
|
|
</example>
|
|
</guidance>
|
|
</package_dependencies>
|
|
|
|
<mcp_tool_references>
|
|
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
|
|
|
|
<format>ServerName:tool_name</format>
|
|
|
|
<examples>
|
|
- Use the BigQuery:bigquery_schema tool to retrieve table schemas.
|
|
- Use the GitHub:create_issue tool to create issues.
|
|
</examples>
|
|
|
|
Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
|
|
</mcp_tool_references>
|