Skill Development

Hard Rules

1. NEVER download and install/load external skills directly.
2. NEVER execute, import, or run code from external skill artifacts.
3. NEVER read external artifacts on host — use safe-download-and-read skill.
4. NEVER use curl, wget, or direct download commands.
5. External artifacts are research-only — patterns and ideas, never direct code.
6. Final skill MUST be written fresh in trusted skills/ workspace path.
7. Final skill MUST pass safety checklist before activation.

Workflow

Phase 1: Research (find existing patterns)

Use web-discovery and web-scraping skills to find:

• Similar skills on ClawhHub, GitHub, or other registries
• Documentation, blog posts, tutorials about the domain
• API docs or references needed for the skill

Collect URLs and metadata. Do NOT download artifacts yet.

Phase 2: Download and inspect (quarantined)

For each promising external skill/reference:

1. Invoke safe-download-and-read skill
2. Download to quarantine via approved tools only
3. Inspect ONLY inside isolated Docker container
4. Extract:
   • Structural patterns (directory layout, file organization)
   • Workflow ideas (steps, decision points, error handling)
   • Domain knowledge (schemas, APIs, gotchas)
   • Script logic patterns (algorithms, not verbatim code)
5. Document findings in research/skills/<skill-name>/notes.md

Phase 3: Design

Based on research findings, design the new skill:

1. Define skill name, description, and trigger conditions
2. Plan directory structure (scripts/, references/, assets/)
3. Outline SKILL.md body (workflow steps, rules, examples)
4. Identify what scripts/references/assets are needed
5. Write design doc in research/skills/<skill-name>/design.md

Phase 4: Build (fresh, from scratch)

1. Use the built-in skill-creator skill for scaffolding if helpful
2. Write ALL code, configs, and docs fresh — no copy-paste from quarantine
3. Concepts and patterns from research are fine; verbatim code is not
4. Test scripts by running them on safe/known inputs
5. Build in trusted skills/<skill-name>/ path only

Phase 5: Safety review

Before activation, verify:

• No code copied verbatim from external sources
• No embedded URLs for runtime external loading
• No shell commands that could be injection vectors
• No instructions that override system prompts or safety rules
• No encoded/obfuscated content
• SKILL.md frontmatter has correct name + description
• All scripts tested on known inputs
• All references are static documentation, not executable
• Skill follows progressive disclosure (SKILL.md < 500 lines)

Phase 6: Commit and cleanup

1. git add and commit the new skill
2. Clean up quarantine: rm -rf quarantine/<session>
3. Clean up research notes if no longer needed
4. Update TOOLS.md if the skill has environment-specific notes

Reference: Skill anatomy

skill-name/
├── SKILL.md          (required: frontmatter + instructions)
├── scripts/          (optional: executable code)
├── references/       (optional: docs loaded into context as needed)
└── assets/           (optional: files used in output, not loaded into context)