Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
280
.claude/skills/.SKILL_TEMPLATE.md
Normal file
280
.claude/skills/.SKILL_TEMPLATE.md
Normal file
@@ -0,0 +1,280 @@
|
||||
---
|
||||
name: Skill Name Here
|
||||
description: Brief, specific description of what this skill does and when Claude should use it. Include trigger words and file types. Use when [specific scenarios]. Keywords: [relevant terms users might mention].
|
||||
allowed-tools: Read, Grep, Glob
|
||||
# Optional: Restrict which tools Claude can use when this skill is active
|
||||
# Omit this field if the skill should follow standard permission model
|
||||
# Common tool combinations:
|
||||
# - Read-only: Read, Grep, Glob
|
||||
# - File operations: Read, Write, Edit, Glob, Grep
|
||||
# - Git operations: Bash(git status), Bash(git diff), Bash(git log)
|
||||
# - Execution: Bash, Read, Write
|
||||
---
|
||||
|
||||
# Skill Name Here
|
||||
|
||||
> **Purpose**: One-sentence explanation of the skill's primary purpose.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Brief example of the most common use case:
|
||||
|
||||
```language
|
||||
# Quick example code or command
|
||||
example_command()
|
||||
```
|
||||
|
||||
## Instructions
|
||||
|
||||
Detailed step-by-step guidance for Claude on how to use this skill:
|
||||
|
||||
1. **First step**: What to do first
|
||||
- Use [specific tool] to gather information
|
||||
- Check for [specific conditions]
|
||||
|
||||
2. **Second step**: Next action
|
||||
- Process the information
|
||||
- Apply [specific logic or rules]
|
||||
|
||||
3. **Third step**: Final actions
|
||||
- Generate output in [specific format]
|
||||
- Verify [specific criteria]
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Claude should activate this skill when:
|
||||
- User mentions [specific keywords]
|
||||
- Working with [specific file types or patterns]
|
||||
- Task involves [specific operations]
|
||||
- User asks about [specific topics]
|
||||
|
||||
## Requirements
|
||||
|
||||
### Prerequisites
|
||||
- Required tools or dependencies
|
||||
- Expected file structures
|
||||
- Necessary permissions
|
||||
|
||||
### Environment
|
||||
- Operating system considerations
|
||||
- Path requirements
|
||||
- Configuration needs
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Common Use Case
|
||||
```language
|
||||
# Code example showing typical usage
|
||||
def example_function():
|
||||
"""Clear docstring."""
|
||||
pass
|
||||
```
|
||||
|
||||
**Context**: When to use this approach
|
||||
**Expected Output**: What Claude should produce
|
||||
|
||||
### Example 2: Advanced Use Case
|
||||
```language
|
||||
# More complex example
|
||||
advanced_example()
|
||||
```
|
||||
|
||||
**Context**: When this is needed
|
||||
**Expected Output**: Expected result
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
- ✅ Specific recommendation with rationale
|
||||
- ✅ Another best practice
|
||||
- ✅ Tool usage guidelines
|
||||
|
||||
### Don'ts
|
||||
- ❌ What to avoid and why
|
||||
- ❌ Common mistakes
|
||||
- ❌ Anti-patterns
|
||||
|
||||
## Output Format
|
||||
|
||||
Specify the expected output structure:
|
||||
|
||||
```markdown
|
||||
## Section Title
|
||||
- Item 1
|
||||
- Item 2
|
||||
|
||||
### Subsection
|
||||
Details here...
|
||||
```
|
||||
|
||||
Or for code:
|
||||
```language
|
||||
// Expected code structure
|
||||
class Example {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
### Issue 1: Specific Problem
|
||||
**Symptoms**: What the user sees
|
||||
**Cause**: Why it happens
|
||||
**Solution**: How to fix it
|
||||
|
||||
### Issue 2: Another Problem
|
||||
**Symptoms**: Description
|
||||
**Cause**: Root cause
|
||||
**Solution**: Fix steps
|
||||
|
||||
## Related Files
|
||||
|
||||
Link to supporting documentation or resources:
|
||||
- [Additional reference](reference.md) - Detailed API documentation
|
||||
- [Examples collection](examples.md) - More usage examples
|
||||
- [Advanced guide](advanced.md) - Deep dive into complex scenarios
|
||||
|
||||
## Tool Permissions
|
||||
|
||||
This skill uses the following tools:
|
||||
- **Read**: For reading file contents
|
||||
- **Grep**: For searching code patterns
|
||||
- **Glob**: For finding files
|
||||
|
||||
> **Note**: If `allowed-tools` is specified in frontmatter, Claude can only use those tools without asking permission when this skill is active.
|
||||
|
||||
## Version History
|
||||
|
||||
Track changes to this skill:
|
||||
|
||||
- **v1.0.0** (YYYY-MM-DD): Initial release
|
||||
- Core functionality
|
||||
- Basic examples
|
||||
|
||||
- **v1.1.0** (YYYY-MM-DD): Enhancement description
|
||||
- New feature added
|
||||
- Improved handling of edge case
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before considering this skill complete:
|
||||
|
||||
- [ ] Skill activates on appropriate prompts
|
||||
- [ ] Instructions are clear and unambiguous
|
||||
- [ ] Examples work as documented
|
||||
- [ ] Error handling covers common issues
|
||||
- [ ] Output format is consistent
|
||||
- [ ] Tool permissions are appropriate
|
||||
- [ ] Description includes trigger keywords
|
||||
- [ ] Related files are accessible
|
||||
- [ ] Team members can use successfully
|
||||
|
||||
## Notes
|
||||
|
||||
Additional context, tips, or warnings:
|
||||
|
||||
- Important consideration about usage
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
- Compatibility notes
|
||||
|
||||
---
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### Writing the Description (Frontmatter)
|
||||
|
||||
The `description` field is **critical** for skill discovery. Follow these rules:
|
||||
|
||||
1. **Be Specific**: Include exact terms users would say
|
||||
- ❌ "Helps with files"
|
||||
- ✅ "Process PDF files, extract text, fill forms. Use when working with PDFs or document extraction."
|
||||
|
||||
2. **Include Triggers**: Add keywords that should activate the skill
|
||||
- File types: PDF, .xlsx, .json
|
||||
- Operations: analyze, generate, convert, test
|
||||
- Technologies: React, Python, SQL
|
||||
|
||||
3. **Combine What + When**:
|
||||
```yaml
|
||||
description: [What it does]. Use when [specific scenarios]. Keywords: [terms].
|
||||
```
|
||||
|
||||
### Choosing Allowed Tools
|
||||
|
||||
Only include `allowed-tools` if you want to **restrict** Claude's capabilities:
|
||||
|
||||
- **Read-only skill**: `allowed-tools: Read, Grep, Glob`
|
||||
- **Code modification**: `allowed-tools: Read, Edit, Grep, Glob`
|
||||
- **Full file operations**: `allowed-tools: Read, Write, Edit, Glob, Grep, Bash`
|
||||
- **Omit field**: For standard permission model (recommended default)
|
||||
|
||||
### Organizing Supporting Files
|
||||
|
||||
For multi-file skills, structure as:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (main skill file)
|
||||
├── reference.md (detailed API/reference docs)
|
||||
├── examples.md (extensive examples)
|
||||
├── advanced.md (complex scenarios)
|
||||
└── scripts/ (helper scripts)
|
||||
├── helper.py
|
||||
└── validator.sh
|
||||
```
|
||||
|
||||
Reference them in SKILL.md with relative paths: `[reference](reference.md)`
|
||||
|
||||
### Writing Clear Instructions
|
||||
|
||||
1. **Use numbered steps** for sequential processes
|
||||
2. **Use bullet points** for non-sequential information
|
||||
3. **Bold key actions** for emphasis
|
||||
4. **Include decision points**: "If X, then do Y; otherwise do Z"
|
||||
5. **Specify tools to use**: "Use the Read tool to..." not just "Read the file"
|
||||
|
||||
### Testing Your Skill
|
||||
|
||||
After creating a skill, test with prompts that:
|
||||
1. Match the description exactly
|
||||
2. Use trigger keywords
|
||||
3. Mention related file types
|
||||
4. Describe the scenario differently
|
||||
5. Come from a teammate's perspective
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Claude loads files **on demand**. Structure content so:
|
||||
- Essential information is in SKILL.md
|
||||
- Detailed references are in separate files
|
||||
- Claude only reads what it needs
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
For basic usage, follow the instructions above.
|
||||
For advanced scenarios, see [advanced.md](advanced.md).
|
||||
For complete API reference, see [reference.md](reference.md).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
| Element | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| `name` | Skill display name | ✅ Yes |
|
||||
| `description` | Discovery & when to use | ✅ Yes |
|
||||
| `allowed-tools` | Restrict tool access | ❌ Optional |
|
||||
| Instructions | Step-by-step guidance | ✅ Yes |
|
||||
| Examples | Concrete usage demos | ✅ Recommended |
|
||||
| Best Practices | Do's and don'ts | ✅ Recommended |
|
||||
| Error Handling | Troubleshooting | ❌ Optional |
|
||||
| Related Files | Supporting docs | ❌ As needed |
|
||||
| Version History | Track changes | ✅ Recommended |
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Skills are about **packaging expertise** so Claude can apply specialized knowledge at the right time. Keep them focused, clear, and well-tested.
|
||||
303
.claude/skills/pdf-processor/SKILL.md
Normal file
303
.claude/skills/pdf-processor/SKILL.md
Normal file
@@ -0,0 +1,303 @@
|
||||
---
|
||||
name: pdf-processor
|
||||
description: Extract text, tables, and metadata from PDF files, fill PDF forms, and merge/split PDFs. Use when user mentions PDFs, documents, forms, or needs to extract content from PDF files.
|
||||
allowed-tools: Read, Bash(python *:*), Bash(pip *:*), Write
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# PDF Processor Skill
|
||||
|
||||
Process PDF files: extract text/tables, read metadata, fill forms, merge/split documents.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### 1. Text Extraction
|
||||
Extract text content from PDF files for analysis or conversion.
|
||||
|
||||
### 2. Table Extraction
|
||||
Extract tables from PDFs and convert to CSV, JSON, or markdown.
|
||||
|
||||
### 3. Metadata Reading
|
||||
Read PDF metadata (author, creation date, page count, etc.).
|
||||
|
||||
### 4. Form Filling
|
||||
Fill interactive PDF forms programmatically.
|
||||
|
||||
### 5. Document Manipulation
|
||||
- Merge multiple PDFs
|
||||
- Split PDFs into separate pages
|
||||
- Extract specific pages
|
||||
|
||||
## Trigger Words
|
||||
|
||||
Use this skill when user mentions:
|
||||
- PDF files, documents
|
||||
- "extract from PDF", "read PDF", "parse PDF"
|
||||
- "PDF form", "fill form"
|
||||
- "merge PDFs", "split PDF", "combine PDFs"
|
||||
- "PDF to text", "PDF to CSV"
|
||||
|
||||
## Dependencies
|
||||
|
||||
This skill uses Python's `PyPDF2` and `pdfplumber` libraries:
|
||||
|
||||
```bash
|
||||
pip install PyPDF2 pdfplumber
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Extract Text
|
||||
```
|
||||
User: "Extract text from report.pdf"
|
||||
Assistant: [Uses this skill to extract and display text]
|
||||
```
|
||||
|
||||
### Example 2: Extract Tables
|
||||
```
|
||||
User: "Get the data table from financial-report.pdf"
|
||||
Assistant: [Extracts tables and converts to markdown/CSV]
|
||||
```
|
||||
|
||||
### Example 3: Read Metadata
|
||||
```
|
||||
User: "What's in this PDF? Show me the metadata"
|
||||
Assistant: [Displays author, page count, creation date, etc.]
|
||||
```
|
||||
|
||||
## Instructions
|
||||
|
||||
When this skill is invoked:
|
||||
|
||||
### Step 1: Verify Dependencies
|
||||
Check if required Python libraries are installed:
|
||||
```bash
|
||||
python -c "import PyPDF2, pdfplumber" 2>/dev/null || echo "Need to install"
|
||||
```
|
||||
|
||||
If not installed, ask user permission to install:
|
||||
```bash
|
||||
pip install PyPDF2 pdfplumber
|
||||
```
|
||||
|
||||
### Step 2: Determine Task Type
|
||||
|
||||
Ask clarifying questions if ambiguous:
|
||||
- "Would you like to extract text, tables, or metadata?"
|
||||
- "Do you need all pages or specific pages?"
|
||||
- "What output format do you prefer?"
|
||||
|
||||
### Step 3: Execute Based on Task
|
||||
|
||||
#### For Text Extraction:
|
||||
|
||||
```python
|
||||
import PyPDF2
|
||||
|
||||
def extract_text(pdf_path):
|
||||
with open(pdf_path, 'rb') as file:
|
||||
reader = PyPDF2.PdfReader(file)
|
||||
text = ""
|
||||
for page in reader.pages:
|
||||
text += page.extract_text() + "\n\n"
|
||||
return text
|
||||
|
||||
# Usage
|
||||
text = extract_text("path/to/file.pdf")
|
||||
print(text)
|
||||
```
|
||||
|
||||
#### For Table Extraction:
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
|
||||
def extract_tables(pdf_path):
|
||||
tables = []
|
||||
with pdfplumber.open(pdf_path) as pdf:
|
||||
for page in pdf.pages:
|
||||
page_tables = page.extract_tables()
|
||||
if page_tables:
|
||||
tables.extend(page_tables)
|
||||
return tables
|
||||
|
||||
# Usage
|
||||
tables = extract_tables("path/to/file.pdf")
|
||||
# Convert to markdown or CSV as needed
|
||||
```
|
||||
|
||||
#### For Metadata:
|
||||
|
||||
```python
|
||||
import PyPDF2
|
||||
|
||||
def get_metadata(pdf_path):
|
||||
with open(pdf_path, 'rb') as file:
|
||||
reader = PyPDF2.PdfReader(file)
|
||||
info = reader.metadata
|
||||
return {
|
||||
'Author': info.get('/Author', 'Unknown'),
|
||||
'Title': info.get('/Title', 'Unknown'),
|
||||
'Subject': info.get('/Subject', 'Unknown'),
|
||||
'Creator': info.get('/Creator', 'Unknown'),
|
||||
'Producer': info.get('/Producer', 'Unknown'),
|
||||
'CreationDate': info.get('/CreationDate', 'Unknown'),
|
||||
'ModDate': info.get('/ModDate', 'Unknown'),
|
||||
'Pages': len(reader.pages)
|
||||
}
|
||||
|
||||
# Usage
|
||||
metadata = get_metadata("path/to/file.pdf")
|
||||
for key, value in metadata.items():
|
||||
print(f"{key}: {value}")
|
||||
```
|
||||
|
||||
#### For Merging PDFs:
|
||||
|
||||
```python
|
||||
import PyPDF2
|
||||
|
||||
def merge_pdfs(pdf_list, output_path):
|
||||
merger = PyPDF2.PdfMerger()
|
||||
for pdf in pdf_list:
|
||||
merger.append(pdf)
|
||||
merger.write(output_path)
|
||||
merger.close()
|
||||
|
||||
# Usage
|
||||
merge_pdfs(["file1.pdf", "file2.pdf"], "merged.pdf")
|
||||
```
|
||||
|
||||
#### For Splitting PDFs:
|
||||
|
||||
```python
|
||||
import PyPDF2
|
||||
|
||||
def split_pdf(pdf_path, output_dir):
|
||||
with open(pdf_path, 'rb') as file:
|
||||
reader = PyPDF2.PdfReader(file)
|
||||
for i, page in enumerate(reader.pages):
|
||||
writer = PyPDF2.PdfWriter()
|
||||
writer.add_page(page)
|
||||
output_file = f"{output_dir}/page_{i+1}.pdf"
|
||||
with open(output_file, 'wb') as output:
|
||||
writer.write(output)
|
||||
|
||||
# Usage
|
||||
split_pdf("document.pdf", "output/")
|
||||
```
|
||||
|
||||
### Step 4: Present Results
|
||||
|
||||
- For text: Display extracted content or save to file
|
||||
- For tables: Format as markdown table or save as CSV
|
||||
- For metadata: Display in readable format
|
||||
- For operations: Confirm success and output location
|
||||
|
||||
### Step 5: Offer Next Steps
|
||||
|
||||
Suggest related actions:
|
||||
- "Would you like me to save this to a file?"
|
||||
- "Should I analyze this content?"
|
||||
- "Need to extract data from other PDFs?"
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
1. **File not found**
|
||||
- Verify path exists
|
||||
- Check file permissions
|
||||
|
||||
2. **Encrypted PDF**
|
||||
- Ask user for password
|
||||
- Use `reader.decrypt(password)`
|
||||
|
||||
3. **Corrupted PDF**
|
||||
- Inform user
|
||||
- Suggest using `pdfplumber` as alternative
|
||||
|
||||
4. **Missing dependencies**
|
||||
- Install PyPDF2 and pdfplumber
|
||||
- Provide installation commands
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always verify file path** before processing
|
||||
2. **Ask for confirmation** before installing dependencies
|
||||
3. **Handle large PDFs** carefully (show progress for many pages)
|
||||
4. **Preserve formatting** when extracting tables
|
||||
5. **Offer multiple output formats** (text, CSV, JSON, markdown)
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
This skill has access to:
|
||||
- `Read` - For reading file paths and existing content
|
||||
- `Bash(python *:*)` - For running Python scripts
|
||||
- `Bash(pip *:*)` - For installing dependencies
|
||||
- `Write` - For saving extracted content
|
||||
|
||||
**No access to** other tools to maintain focus.
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before using with real user data:
|
||||
|
||||
- [ ] Test with simple single-page PDF
|
||||
- [ ] Test with multi-page PDF
|
||||
- [ ] Test with PDF containing tables
|
||||
- [ ] Test with encrypted PDF
|
||||
- [ ] Test merge operation
|
||||
- [ ] Test split operation
|
||||
- [ ] Verify error handling works
|
||||
- [ ] Check output formatting is clear
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Form Filling
|
||||
|
||||
```python
|
||||
from PyPDF2 import PdfReader, PdfWriter
|
||||
|
||||
def fill_form(template_path, data, output_path):
|
||||
reader = PdfReader(template_path)
|
||||
writer = PdfWriter()
|
||||
|
||||
# Fill form fields
|
||||
writer.append_pages_from_reader(reader)
|
||||
writer.update_page_form_field_values(
|
||||
writer.pages[0], data
|
||||
)
|
||||
|
||||
with open(output_path, 'wb') as output:
|
||||
writer.write(output)
|
||||
```
|
||||
|
||||
### OCR for Scanned PDFs
|
||||
|
||||
For scanned PDFs (images), suggest using OCR:
|
||||
```bash
|
||||
pip install pdf2image pytesseract
|
||||
# Requires tesseract-ocr system package
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
- **1.0.0** (2025-10-20): Initial release
|
||||
- Text extraction
|
||||
- Table extraction
|
||||
- Metadata reading
|
||||
- Merge/split operations
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **document-converter** - Convert between document formats
|
||||
- **data-analyzer** - Analyze extracted data
|
||||
- **report-generator** - Create reports from PDF data
|
||||
|
||||
## Notes
|
||||
|
||||
- Works best with text-based PDFs
|
||||
- For scanned PDFs, recommend OCR tools
|
||||
- Large PDFs may take time to process
|
||||
- Always preserve user's original files
|
||||
Reference in New Issue
Block a user