Skill Publisher

Prepare a skill for public release. Run through this checklist before publishing any skill to ensure it's reusable, clean, safe, and well-documented.

When to Use

• Before pushing a skill to a public repo
• Before submitting to ClawdHub
• When reviewing someone else's skill
• Periodic audits of existing published skills

Quick Checklist

Run through these in order. Each section has detailed guidance below.

[ ] 1. STRUCTURE    - Required files present, logical organization
[ ] 2. SECURITY     - No secrets, keys, PII, or sensitive data  
[ ] 3. PORTABILITY  - No hardcoded paths, works on any machine
[ ] 4. QUALITY      - Clean code, no debug artifacts
[ ] 5. DOCS         - README, SKILL.md, examples complete
[ ] 6. TESTING      - Verified it actually works
[ ] 7. GIT          - Clean history, proper .gitignore, good commits

---

1. Structure Validation

Required Files

skill-name/
├── SKILL.md          # REQUIRED - Entry point, when to use, quick reference
├── README.md         # REQUIRED - For GitHub/humans
└── [content files]   # The actual skill content

SKILL.md Format

Must include:

• Header: Name and one-line description
• When to Use: Clear triggers for loading this skill
• Quick Reference: Most important info at a glance
• Detailed sections: As needed

# Skill Name

One-line description of what this skill does.

## When to Use
- Trigger condition 1
- Trigger condition 2

## Quick Reference
[Most important info here]

## [Additional Sections]
[Detailed content]

File Organization

• Group related content logically
• Use clear, descriptive filenames
• Keep files focused (single responsibility)
• Consider load order (what gets read first?)

Anti-patterns

❌ Single massive file with everything ❌ Cryptic filenames (data1.md, stuff.md) ❌ Circular dependencies between files ❌ Missing SKILL.md entry point

---

2. Security Audit

Secrets Scan

Search for and REMOVE:

# Run in skill directory
grep -rniE "(api[_-]?key|secret|password|token|bearer|auth)" . --include="*.md"
grep -rniE "([a-zA-Z0-9]{32,})" . --include="*.md"  # Long strings that might be keys
grep -rniE "(sk-|pk-|xai-|ghp_|gho_)" . --include="*.md"  # Common key prefixes

Personal Data Scan

Search for and REMOVE:

grep -rniE "(@gmail|@yahoo|@hotmail|@proton)" . --include="*.md"
grep -rniE "\+?[0-9]{10,}" . --include="*.md"  # Phone numbers
grep -rniE "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}" . --include="*.md"  # IPs

Sensitive Content Check

• ○No internal company information
• ○No private URLs or endpoints
• ○No employee names (unless public figures)
• ○No financial data
• ○No credentials of any kind
• ○No session tokens or cookies

Example Data

If examples need realistic data, use:

• user@example.com for emails
• 192.0.2.x for IPs (RFC 5737 documentation range)
• example.com for domains
• Clearly fake names ("Alice", "Bob", "Acme Corp")

---

3. Portability Check

Path Hardcoding

Search and fix:

grep -rniE "(\/home\/|\/Users\/|C:\\\\|~\/)" . --include="*.md"
grep -rniE "\/[a-z]+\/[a-z]+\/" . --include="*.md"  # Absolute paths

Replace with:

• Relative paths (./config.yaml)


• Environment variables ($HOME, $XDG_CONFIG_HOME)


• Platform-agnostic descriptions

Environment Assumptions

• ○No hardcoded usernames


• ○No machine-specific paths


• ○No assumed installed software (or document requirements)


• ○No assumed environment variables (or document them)


• ○No OS-specific commands without alternatives

Dependency Documentation

If the skill requires external tools:

## Requirements
- `tool-name` - [installation link]
- Environment variable `API_KEY` must be set

---

4. Code Quality

Debug Artifacts

Remove:

grep -rniE "(TODO|FIXME|XXX|HACK|DEBUG)" . --include="*.md"
grep -rniE "(console\.log|print\(|debugger)" . --include="*.md"

Formatting

• ○Consistent markdown style
• ○Code blocks have language tags (``python, `bash) - [ ] Tables render correctly - [ ] Links work (no broken references) - [ ] No trailing whitespace - [ ] Consistent heading hierarchy ### Content Quality - [ ] No filler text (e.g., Lorem-ipsum, incomplete markers) - [ ] No commented-out sections - [ ] No duplicate content - [ ] No outdated information - [ ] Examples are complete and runnable --- ## 5. Documentation ### README.md Checklist __CODE_BLOCK_8__ ### SKILL.md Checklist - [ ] Clear "When to Use" section with specific triggers - [ ] Quick reference for most common needs - [ ] Logical organization of detailed content - [ ] Cross-references to other files if multi-file ### Examples - [ ] At least one complete, working example - [ ] Examples use safe/fake data - [ ] Examples are tested and verified --- ## 6. Testing ### Functional Testing 1. **Fresh load test**: Load skill in new session, verify it makes sense 2. **Trigger test**: Verify "When to Use" conditions actually match use cases 3. **Example test**: Run through all examples manually 4. **Edge case test**: What happens with unusual inputs? ### Integration Testing If skill involves tools/commands: __CODE_BLOCK_9__ ### Cross-Reference Testing - [ ] All internal links work - [ ] All external links are valid - [ ] File references are correct ### Verification Script (optional but recommended) Create test.sh or document manual test steps: __CODE_BLOCK_10__ --- ## 7. Git Hygiene ### Before First Commit Create .gitignore: __CODE_BLOCK_11__ ### Commit History - [ ] No secrets ever committed (check full history!) - [ ] Clean, atomic commits - [ ] Meaningful commit messages __CODE_BLOCK_12__ If secrets were ever committed: __CODE_BLOCK_13__ ### Commit Message Format __CODE_BLOCK_14__ ### Pre-Push Checklist __CODE_BLOCK_15__ --- ## 8. Metadata ### Repository Settings - [ ] Description filled in - [ ] Topics/tags added (e.g., claw, skill, ai-assistant) For open skills, MIT is simple and permissive: __CODE_BLOCK_16__ ### ClawdHub Metadata (if publishing there) In SKILL.md frontmatter: __CODE_BLOCK_17__ --- ## Automated Audit Script Run this before every publish: __CODE_BLOCK_18__ --- ## Publishing Flow __CODE_BLOCK_19__ ## README Quality A good README is discoverable and human-readable. See docs/readme-quality.md` for detailed guidance.

Quick Checks

• First line explains what it does (not "Welcome to...")
• No AI buzzwords (comprehensive, seamless, leverage, cutting-edge)
• Specific use cases, not vague claims
• Sounds like a person, not a press release
• No excessive emoji decoration in headers

SEO Tips

• Use phrases people actually search for
• Put most important info in first paragraph
• Be specific about features (not "powerful validation" but "checks for API keys")

Post-Publish

• ○Verify GitHub renders correctly
• ○Test fresh clone works
• ○Add to your AGENTS.md skill list if using locally
• ○Announce if relevant (Discord, etc.)