tomevault-io Skill Name
Philosophy: Default to natural language. Use scripts ONLY for deterministic operations, complex I/O, or external API integration.
Quick Start
[Concise example showing the most common use case - assume Claude is smart]
Example:
# Process document
python3 scripts/process.py input.pdf --output result.txt
When to Use This Skill
Use this skill when:
- [Specific scenario 1]
- [Specific scenario 2]
- [Keyword trigger mentioned by user]
DO NOT use when:
- [Alternative approach is better]
Core Workflows
Workflow 1: [Name]
Use when: [Specific trigger or scenario]
Steps:
- [Natural language instruction - be specific]
- [Conditional logic: If X, then Y; else Z]
- [Verification step]
Example:
1. Check if document exists: `ls docs/*.pdf`
2. If PDF found: Extract text using `scripts/extract.py`
3. If no PDF: Search for DOCX alternatives
4. Validate output has non-zero size
Common Issues:
- Problem: [What goes wrong]
- Solution: [How to fix it]
Workflow 2: [Name]
[Follow same pattern as Workflow 1]
Reference Documentation
For detailed information, see:
- Topic A Details - When working with X
- Topic B Details - For advanced Y usage
- API Reference - All available functions
Note: Claude loads these files ONLY when needed (progressive disclosure).
Scripts (ONLY when justified)
script-name.py
Why this script is needed: [ONE of these justifications]:
- ✅ Deterministic validation (e.g., schema validation, syntax checking)
- ✅ External API integration (e.g., GitHub API, third-party service)
- ✅ Complex I/O operation (e.g., scanning thousands of files, binary parsing)
- ✅ Safety-critical operation (e.g., git worktree, database migrations)
- ❌ NOT for: Pattern matching, text analysis, conditional logic (Claude is better)
Usage:
python3 scripts/script-name.py --arg value
Arguments:
--arg: Description
Output:
Expected output format
Error Handling: Script handles these errors explicitly (doesn't punt to Claude):
- Missing input file → Creates default
- Permission denied → Uses alternative path
- Network timeout → Retries with backoff
validation-script.sh
Why needed: [Justification - e.g., "Bash validation faster than Python for simple checks"]
Usage:
./scripts/validation-script.sh file.txt
Returns:
- Exit code 0: Valid
- Exit code 1: Invalid (with error message)
Testing
Run Tests
# Unit tests
pytest tests/unit/ -v
# Integration tests
pytest tests/integration/ -v
# Specific test
pytest tests/test_specific.py::test_function -v
Test Coverage
Current coverage: XX%
pytest --cov=scripts --cov-report=html
open htmlcov/index.html
Examples
Example 1: [Common Use Case]
Scenario: [Describe the situation]
Input:
[What user provides]
Process:
1. Claude reads input
2. Validates format
3. Calls script if needed: `python3 scripts/process.py`
4. Formats output
Output:
[What user gets]
Example 2: [Edge Case]
[Same structure as Example 1]
Integration
With Other Skills
This skill integrates with:
- skill-a: Use after this skill for [purpose]
- skill-b: Call this skill if [condition]
With Agents
Agents that use this skill:
- agent-x (Phase Y): Uses for [specific task]
- agent-z (Phase W): Calls during [workflow step]
Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
VAR_NAME |
No | default |
What this controls |
Settings File
Create ~/.config/skill-name/settings.yml:
option1: value1
option2: value2
Troubleshooting
Common Issues
Issue: Script fails with "Module not found"
Solution:
pip install required-package
Issue: Permission denied
Solution:
chmod +x scripts/*.sh
chmod +x scripts/*.py
Issue: Output is empty
Solution: Check input file format. Expected: [format description]
Development
Adding New Features
- Create feature branch
- Add tests FIRST (TDD)
- Implement in natural language if possible
- Add script ONLY if justified
- Update SKILL.md
- Run tests:
pytest -v
Code Style
- Natural language: Clear, concise, assume Claude is smart
- Python: PEP 8, type hints, docstrings
- Bash: ShellCheck compliant
Changelog
v1.0.0 (YYYY-MM-DD)
- Initial release
- Core workflows implemented
- [Feature X] added
References
Anti-Patterns to Avoid
❌ DON'T:
- Create scripts for pattern matching (Claude is better)
- Write Python for simple Bash operations
- Add dependencies without justification
- Create "utils" or "helpers" (be specific)
✅ DO:
- Default to natural language instructions
- Use progressive disclosure for > 500 lines
- Document why each script is needed
- Test with Claude before assuming script is needed
Skill maintained by: [Team/Person] Last updated: YYYY-MM-DD Questions: Contact [channel/person]
Converted and distributed by TomeVault — claim your Tome and manage your conversions.