commit fb49f811dae9e55a9adb7121b661afe0898ecd65 Author: ai_member_only Date: Wed Apr 1 23:14:48 2026 +0800 auto-sync: skill-builder 2026-04-01_23:14 diff --git a/.clawhub/origin.json b/.clawhub/origin.json new file mode 100644 index 0000000..2409d1d --- /dev/null +++ b/.clawhub/origin.json @@ -0,0 +1,7 @@ +{ + "version": 1, + "registry": "https://clawhub.ai", + "slug": "skill-builder", + "installedVersion": "1.0.5", + "installedAt": 1772328256596 +} diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..121492b --- /dev/null +++ b/SKILL.md @@ -0,0 +1,104 @@ +--- +name: Skill Builder / Creator +slug: skill-builder +version: 1.0.5 +homepage: https://clawic.com/skills/skill-builder +description: Create high-quality skills with modular structure, progressive disclosure, and token-efficient design. +changelog: Added description examples table, security checklist, and improved traps with fixes +metadata: {"clawdbot":{"emoji":"πŸ› οΈ","requires":{"bins":[]},"os":["linux","darwin","win32"]}} +--- + +## Setup + +On first use, read `setup.md` for integration guidelines. + +## When to Use + +User wants to create or improve a skill. Agent guides structure, reviews content, and ensures quality. + +## Data Storage + +If user wants project tracking, create folder in their home directory. +See `memory-template.md` for the template structure. + +The agent does NOT create files automatically. Always ask user first. + +## Architecture + +Skills follow this structure: + +``` +skill-name/ +β”œβ”€β”€ SKILL.md # Core instructions (SHORT) +β”œβ”€β”€ [topic].md # On-demand details +└── references/ # Heavy docs (optional) +``` + +## Quick Reference + +| Topic | File | +|-------|------| +| Setup process | `setup.md` | +| Tracking projects | `memory-template.md` | +| Patterns and examples | `patterns.md` | + +## Core Rules + +### 1. SKILL.md Must Be Short +Target 30-50 lines, max 80. Move details to auxiliary files. Every line must justify its token cost. + +### 2. Progressive Disclosure +``` +Level 1: Metadata (name + description) β€” always loaded +Level 2: SKILL.md body β€” when skill triggers +Level 3: Auxiliary files β€” on demand +``` + +### 3. Descriptions Are Critical +One sentence, 15-25 words. Action verb first. Describes capabilities, not triggers. + +| ❌ Wrong | βœ… Right | +|----------|----------| +| "Use when user needs PDFs" | "Process, merge, and extract PDF content" | +| "Helper for Docker" | "Build, deploy, and debug Docker containers" | +| "Git guide" | "Manage branches, resolve conflicts, and automate workflows" | + +See `patterns.md` for more examples. + +### 4. Required Structure +Every skill needs: +- Frontmatter: name, slug, version, description +- `## When to Use` β€” activation triggers +- `## Core Rules` β€” 3-7 numbered rules + +### 5. Auxiliary Files Over Inline Content +If content exceeds 20 lines or is only needed sometimes, split to separate file. Reference from Quick Reference table. + +### 6. No Redundancy +Information lives in ONE place. SKILL.md references files, doesn't duplicate content. + +### 7. Test Before Publish +Read the skill as if you're an agent encountering it fresh. Is every instruction clear and necessary? + +## Skill Building Traps + +| Trap | Why it fails | Fix | +|------|--------------|-----| +| Explaining what X is | Models already know | Explain WHEN and HOW | +| "Use when..." in description | Wastes characters | Action verbs only | +| Keyword lists in description | Looks spammy | One clean sentence | +| Templates inline | Bloats SKILL.md | Separate file | +| Vague "observe" instructions | Gets flagged suspicious | Be specific about what data | +| Undeclared file creation | Security flag | Add Data Storage section | + +## Related Skills +Install with `clawhub install ` if user confirms: + +- `skill-manager` β€” manage installed skills +- `skill-update` β€” update existing skills +- `skill-test` β€” test skills locally + +## Feedback + +- If useful: `clawhub star skill-builder` +- Stay updated: `clawhub sync` diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..ce000d1 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1", + "slug": "skill-builder", + "version": "1.0.5", + "publishedAt": 1772061099771 +} \ No newline at end of file diff --git a/memory-template.md b/memory-template.md new file mode 100644 index 0000000..042dfec --- /dev/null +++ b/memory-template.md @@ -0,0 +1,43 @@ +# Memory Template β€” Skill Builder / Creator + +**Optional:** If user wants to track projects, they can create `~/skill-builder/projects.md`. + +Ask user before creating any files. Template: + +```markdown +# Skill Projects + +## Active + +### [skill-name] +- status: drafting | reviewing | ready +- goal: [one sentence] +- files: SKILL.md, setup.md, [others] +- notes: [observations, decisions] +- last: YYYY-MM-DD + +## Completed + +### [skill-name] +- published: YYYY-MM-DD +- version: X.Y.Z +- lessons: [what worked, what to improve] + +--- +*Updated: YYYY-MM-DD* +``` + +## Status Values + +| Value | Meaning | +|-------|---------| +| `drafting` | Writing initial content | +| `reviewing` | Checking structure, testing | +| `ready` | Ready to publish | + +## Usage + +- Add new project when user starts skill +- Update status as work progresses +- Move to Completed after publish +- Capture lessons for future skills diff --git a/patterns.md b/patterns.md new file mode 100644 index 0000000..7708f8f --- /dev/null +++ b/patterns.md @@ -0,0 +1,138 @@ +# Patterns β€” Skill Builder / Creator + +Common patterns for different skill types. + +## Pattern 1: Memory-Based Skills + +Skills that learn and adapt to user preferences. + +``` +skill/ +β”œβ”€β”€ SKILL.md # Instructions + memory reference +β”œβ”€β”€ setup.md # Integration process +β”œβ”€β”€ memory-template.md # Memory structure +└── [domain].md # Domain details +``` + +**Key elements:** +- Memory structure with status tracking +- Rules for when to update memory +- Integration with user's main memory + +## Pattern 2: Tool Integration Skills + +Skills wrapping external tools or APIs. + +``` +skill/ +β”œβ”€β”€ SKILL.md # Workflow + commands +β”œβ”€β”€ setup.md # Installation verification +β”œβ”€β”€ reference.md # Command reference +└── scripts/ # Helper scripts + └── [tool].sh +``` + +**Key elements:** +- External Endpoints table (required) +- Security & Privacy section +- Script manifests +- Error handling guidance + +## Pattern 3: Domain Expert Skills + +Skills providing specialized knowledge. + +``` +skill/ +β”œβ”€β”€ SKILL.md # Overview + rules +β”œβ”€β”€ setup.md # Minimal +β”œβ”€β”€ memory-template.md # Minimal config +└── references/ + β”œβ”€β”€ [topic1].md + └── [topic2].md +``` + +**Key elements:** +- Progressive loading of references +- Clear triggers in description +- Core Rules capture expert judgment + +## Pattern 4: Workflow Skills + +Skills guiding multi-step processes. + +``` +skill/ +β”œβ”€β”€ SKILL.md # Process overview +β”œβ”€β”€ setup.md # Prerequisites +β”œβ”€β”€ memory-template.md # Progress tracking +β”œβ”€β”€ phases/ +β”‚ β”œβ”€β”€ phase1.md +β”‚ └── phase2.md +└── templates/ # Output templates +``` + +**Key elements:** +- Clear phase boundaries +- Progress tracking in memory +- Templates for outputs + +## Description Examples + +### Good Descriptions (copy these patterns) + +| Domain | Description | +|--------|-------------| +| PDF | "Process, merge, and extract PDF content with page manipulation and text extraction." | +| Git | "Manage branches, resolve conflicts, and automate Git workflows with best practices." | +| Docker | "Build, deploy, and debug Docker containers with compose patterns and troubleshooting." | +| API | "Design, document, and test REST APIs with OpenAPI specs and mock servers." | +| Database | "Query, optimize, and migrate databases with schema design and performance tuning." | + +### Bad Descriptions (avoid these) + +| ❌ Bad | Why | +|--------|-----| +| "Use when you need to work with PDFs" | Starts with "Use when" | +| "PDF helper. Triggers: pdf, document, merge" | Multiple sentences, keyword list | +| "A comprehensive guide to Dockerβ€”including containers, images, and more" | Em-dash, vague "more" | +| "Helper for Git stuff" | Too vague, "stuff" | + +### Formula + +``` +[Verb], [verb], and [verb] [technology] with [feature], [feature], and [feature]. +``` + +15-25 words. One sentence. No em-dashes (β€”). No "Use when". + +## Frontmatter Checklist + +```yaml +--- +name: Clear Name # What it is +slug: clear-name # Lowercase, hyphens +version: 1.0.0 # Semver +description: One sentence. # Action verbs. 15-25 words. +--- +``` + +## Quality Checklist + +Before publishing: +- [ ] SKILL.md under 80 lines? +- [ ] Description is one sentence, 15-25 words? +- [ ] All required sections present? +- [ ] No redundancy between files? +- [ ] Core Rules are actionable? +- [ ] Traps are real failure modes? + +## Security Checklist + +Avoid getting flagged as suspicious: +- [ ] No vague words: "silently", "secretly", "automatically" +- [ ] If creating files, add `## Data Storage` section +- [ ] If using APIs, add `## External Endpoints` table +- [ ] If using env vars, declare in metadata requires +- [ ] No "observe", "monitor", "track" without specifying WHAT exactly +- [ ] Always mention "ask user first" for file operations diff --git a/setup.md b/setup.md new file mode 100644 index 0000000..6938d93 --- /dev/null +++ b/setup.md @@ -0,0 +1,53 @@ +# Setup β€” Skill Builder / Creator + +Reference this file when helping users create skills. + +## Your Role + +Help users create effective skills. Guide them through structure, naming, and best practices. + +## Priority Order + +### 1. Understand the Goal + +Ask: +- "What should this skill help with?" +- "What tasks will it handle?" + +Listen for: domain, triggers, audience (human using agent vs agent-to-agent). + +### 2. Identify the Structure + +Based on their goal, determine: +- Does it need memory? (tracks preferences, history, state) +- Does it call external APIs? +- Does it need scripts for deterministic tasks? +- How much auxiliary content? + +### 3. Guide the Build + +Walk them through: +1. Name and description (critical for discovery) +2. Core Rules (what the agent MUST do) +3. Traps (where models fail) +4. File structure + +## Key Principles to Convey + +**Concise over comprehensive:** +"Models are smart. Only add what they don't already know." + +**Progressive disclosure:** +"Details go in separate files, loaded when needed." + +**Description matters most:** +"This is what agents read to decide if your skill matches their query." + +## When Done + +You're ready when: +- Clear understanding of what the skill does +- Draft structure outlined +- User knows what files they need + +Everything else builds iteratively.