skill-packager
Package skills into uploadable ZIP files for Claude. Use after skill-builder/skill-enhancer to create final upload package. Use when relevant to the task.
When & Why to Use This Skill
The Skill Packager is a specialized utility designed to streamline the deployment of Claude AI skills by automating the creation of upload-ready ZIP packages. It ensures that custom AI agents meet all technical requirements through rigorous structural validation, security scanning for sensitive data (like API keys), and file size optimization. This tool is essential for developers looking to move from skill development to production-ready deployment with confidence and efficiency.
Use Cases
- Automated Skill Deployment: Quickly convert developed skill directories into standardized, validated ZIP files ready for immediate upload to the Claude.ai platform.
- Security & Compliance Auditing: Automatically scan skill source files for leaked credentials, passwords, or sensitive tokens before packaging to prevent accidental data exposure.
- Package Optimization & Cleanup: Automatically exclude unnecessary system files, logs, and large assets to ensure the final package remains within Claude's upload limits and maintains a clean structure.
- CI/CD Integration for AI Agents: Integrate the packaging process into automated developer workflows to ensure consistent versioning and reliable delivery of agentic capabilities.
| name | skill-packager |
|---|---|
| description | Package skills into uploadable ZIP files for Claude. Use after skill-builder/skill-enhancer to create final upload package. Use when relevant to the task. |
Skill Packager Skill
Purpose
Single responsibility: Package completed skill directories into ZIP files ready for upload to Claude AI. (BP-4)
Grounding Checkpoint (Archetype 1 Mitigation)
Before executing, VERIFY:
- Skill directory exists with required structure
- SKILL.md is present and non-empty
- At least one reference file exists
- No sensitive data in skill directory
- Output path for ZIP is writable
DO NOT package without validating skill structure.
Uncertainty Escalation (Archetype 2 Mitigation)
ASK USER instead of guessing when:
- Skill structure incomplete - proceed anyway?
- Large files detected - include or exclude?
- Sensitive patterns found (API keys, passwords)
- Multiple skill directories - which to package?
NEVER package potentially sensitive content without review.
Context Scope (Archetype 3 Mitigation)
| Context Type | Included | Excluded |
|---|---|---|
| RELEVANT | Skill directory contents, package config | Other skills |
| PERIPHERAL | Package size estimates | Source data |
| DISTRACTOR | Build process details | Scraping history |
Workflow Steps
Step 1: Validate Skill Structure (Grounding)
# Required structure check
test -f output/<skill-name>/SKILL.md || echo "ERROR: Missing SKILL.md"
test -d output/<skill-name>/references || echo "ERROR: Missing references/"
# Check SKILL.md is not empty
test -s output/<skill-name>/SKILL.md || echo "ERROR: SKILL.md is empty"
# Check for at least one reference
ls output/<skill-name>/references/*.md >/dev/null 2>&1 || echo "ERROR: No reference files"
Step 2: Security Check
# Scan for potential sensitive data
grep -rE "(api[_-]?key|password|secret|token|credential)" output/<skill-name>/ && \
echo "WARNING: Potential sensitive data found - review before packaging"
# Check for large files
find output/<skill-name>/ -size +10M -exec echo "WARNING: Large file: {}" \;
# Check for binary files
find output/<skill-name>/ -type f ! -name "*.md" ! -name "*.json" ! -name "*.txt" \
-exec file {} \; | grep -v "text" && echo "WARNING: Non-text files found"
Step 3: Calculate Package Size
# Estimate final size
du -sh output/<skill-name>/
# Count files
find output/<skill-name>/ -type f | wc -l
# List file types
find output/<skill-name>/ -type f -name "*.*" | sed 's/.*\.//' | sort | uniq -c
Step 4: Create Package
Option A: With skill-seekers
# Standard packaging
skill-seekers package output/<skill-name>/
# With upload (if API key set)
skill-seekers package output/<skill-name>/ --upload
Option B: Manual packaging
# Navigate to output directory
cd output/
# Create ZIP (exclude backups and temp files)
zip -r <skill-name>.zip <skill-name>/ \
-x "*.backup" \
-x "*.tmp" \
-x ".DS_Store" \
-x "__MACOSX/*"
# Verify ZIP contents
unzip -l <skill-name>.zip
Step 5: Validate Package
# Check ZIP integrity
unzip -t output/<skill-name>.zip
# Verify required files are included
unzip -l output/<skill-name>.zip | grep "SKILL.md"
unzip -l output/<skill-name>.zip | grep "references/"
# Check size is reasonable
ls -lh output/<skill-name>.zip
Recovery Protocol (Archetype 4 Mitigation)
On error:
- PAUSE - Don't overwrite existing ZIP
- DIAGNOSE - Check error type:
Missing files→ Run skill-builder firstZIP error→ Check disk space, permissionsLarge size→ Exclude unnecessary filesSensitive data→ Clean files, re-package
- ADAPT - Adjust package configuration
- RETRY - With corrected settings (max 3 attempts)
- ESCALATE - Report packaging issues to user
Checkpoint Support
State saved to: .aiwg/working/checkpoints/skill-packager/
checkpoints/skill-packager/
├── validation_results.json # Pre-package validation
├── security_scan.json # Security check results
├── package_manifest.json # Files included
└── package_log.txt # Packaging process log
Package Manifest
Generate manifest for verification:
{
"skill_name": "myskill",
"packaged_at": "2025-01-15T10:30:00Z",
"files": [
{"path": "SKILL.md", "size": 15234, "hash": "abc123..."},
{"path": "references/index.md", "size": 2045, "hash": "def456..."},
{"path": "references/api.md", "size": 45678, "hash": "ghi789..."}
],
"total_files": 5,
"total_size": 62957,
"package_size": 18234
}
Upload Options
Option 1: Automatic Upload (API)
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers package output/<skill-name>/ --upload
Option 2: Manual Upload
- Package creates
output/<skill-name>.zip - Open output folder automatically
- Go to https://claude.ai/skills
- Click "Upload Skill"
- Select ZIP file
- Done!
Option 3: Via Claude Code (MCP)
"Package and upload the myskill skill"
Exclusion Patterns
Default exclusions:
*.backup
*.tmp
*.log
.DS_Store
__MACOSX/
.git/
node_modules/
__pycache__/
*.pyc
.env
*.key
*.pem
Size Limits
| Platform | Max Size | Recommendation |
|---|---|---|
| Claude.ai | 50MB | Keep under 10MB |
| API | Variable | Keep under 20MB |
If over limit:
- Remove large images
- Compress reference files
- Split into sub-skills
Configuration Options
{
"skill_dir": "output/myskill/",
"output_zip": "output/myskill.zip",
"options": {
"include_manifest": true,
"compress_level": 9,
"exclude_patterns": ["*.backup", "*.tmp"],
"security_check": true,
"auto_upload": false
}
}
Troubleshooting
| Issue | Diagnosis | Solution |
|---|---|---|
| ZIP too large | Large assets | Exclude or compress images |
| Missing files | Validation failed | Run skill-builder first |
| Upload failed | API error | Check API key, retry |
| Corrupt ZIP | Disk issue | Check disk space, re-create |
References
- Claude Skills Upload: https://claude.ai/skills
- Skill Seekers Packaging: https://github.com/jmagly/Skill_Seekers
- REF-001: Production-Grade Agentic Workflows (BP-2 direct functions)
- REF-002: LLM Failure Modes (Archetype 1 grounding before action)