feat(plugin): reorganize compounding-engineering v2.0.0
Major restructure of the compounding-engineering plugin: ## Agents (24 total, now categorized) - review/ (10): architecture-strategist, code-simplicity-reviewer, data-integrity-guardian, dhh-rails-reviewer, kieran-rails-reviewer, kieran-python-reviewer, kieran-typescript-reviewer, pattern-recognition-specialist, performance-oracle, security-sentinel - research/ (4): best-practices-researcher, framework-docs-researcher, git-history-analyzer, repo-research-analyst - design/ (3): design-implementation-reviewer, design-iterator, figma-design-sync - workflow/ (6): bug-reproduction-validator, every-style-editor, feedback-codifier, lint, pr-comment-resolver, spec-flow-analyzer - docs/ (1): ankane-readme-writer ## Commands (15 total) - Moved workflow commands to commands/workflows/ subdirectory - Added: changelog, create-agent-skill, heal-skill, plan_review, prime, reproduce-bug, resolve_parallel, resolve_pr_parallel ## Skills (11 total) - Added: andrew-kane-gem-writer, codify-docs, create-agent-skills, dhh-ruby-style, dspy-ruby, every-style-editor, file-todos, frontend-design, git-worktree, skill-creator - Kept: gemini-imagegen 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -0,0 +1,175 @@
|
||||
<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>
|
||||
Reference in New Issue
Block a user