From e816500baf86d13a4874e3680df564848f56bd1f Mon Sep 17 00:00:00 2001 From: zlei9 Date: Sun, 29 Mar 2026 14:33:54 +0800 Subject: [PATCH] Initial commit with translated description --- SKILL.md | 552 +++++++++++++++++++++++++++++ _meta.json | 6 + assets/LEARNINGS.md | 45 +++ assets/SKILL-TEMPLATE.md | 177 +++++++++ references/clawdbot-integration.md | 311 ++++++++++++++++ references/examples.md | 374 +++++++++++++++++++ references/hooks-setup.md | 223 ++++++++++++ scripts/activator.sh | 20 ++ scripts/error-detector.sh | 55 +++ scripts/extract-skill.sh | 203 +++++++++++ 10 files changed, 1966 insertions(+) create mode 100644 SKILL.md create mode 100644 _meta.json create mode 100644 assets/LEARNINGS.md create mode 100644 assets/SKILL-TEMPLATE.md create mode 100644 references/clawdbot-integration.md create mode 100644 references/examples.md create mode 100644 references/hooks-setup.md create mode 100644 scripts/activator.sh create mode 100644 scripts/error-detector.sh create mode 100644 scripts/extract-skill.sh diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..921008c --- /dev/null +++ b/SKILL.md @@ -0,0 +1,552 @@ +--- +name: self-improvement +description: "捕获学习、错误和更正以实现持续改进。" +--- + +# Self-Improvement Skill + +Log learnings and errors to markdown files for continuous improvement. Coding agents can later process these into fixes, and important learnings get promoted to project memory. + +## Quick Reference + +| Situation | Action | +|-----------|--------| +| Command/operation fails | Log to `.learnings/ERRORS.md` | +| User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` | +| User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` | +| API/external tool fails | Log to `.learnings/ERRORS.md` with integration details | +| Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` | +| Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` | +| Similar to existing entry | Link with `**See Also**`, consider priority bump | +| Broadly applicable learning | Promote to `CLAUDE.md`, `AGENTS.md`, and/or `.github/copilot-instructions.md` | +| Workflow improvements | Promote to `AGENTS.md` (clawdbot workspace) | +| Tool gotchas | Promote to `TOOLS.md` (clawdbot workspace) | +| Behavioral patterns | Promote to `SOUL.md` (clawdbot workspace) | + +## Setup + +Create `.learnings/` directory in project root if it doesn't exist: + +```bash +mkdir -p .learnings +``` + +Copy templates from `assets/` or create files with headers. + +## Logging Format + +### Learning Entry + +Append to `.learnings/LEARNINGS.md`: + +```markdown +## [LRN-YYYYMMDD-XXX] category + +**Logged**: ISO-8601 timestamp +**Priority**: low | medium | high | critical +**Status**: pending +**Area**: frontend | backend | infra | tests | docs | config + +### Summary +One-line description of what was learned + +### Details +Full context: what happened, what was wrong, what's correct + +### Suggested Action +Specific fix or improvement to make + +### Metadata +- Source: conversation | error | user_feedback +- Related Files: path/to/file.ext +- Tags: tag1, tag2 +- See Also: LRN-20250110-001 (if related to existing entry) + +--- +``` + +### Error Entry + +Append to `.learnings/ERRORS.md`: + +```markdown +## [ERR-YYYYMMDD-XXX] skill_or_command_name + +**Logged**: ISO-8601 timestamp +**Priority**: high +**Status**: pending +**Area**: frontend | backend | infra | tests | docs | config + +### Summary +Brief description of what failed + +### Error +``` +Actual error message or output +``` + +### Context +- Command/operation attempted +- Input or parameters used +- Environment details if relevant + +### Suggested Fix +If identifiable, what might resolve this + +### Metadata +- Reproducible: yes | no | unknown +- Related Files: path/to/file.ext +- See Also: ERR-20250110-001 (if recurring) + +--- +``` + +### Feature Request Entry + +Append to `.learnings/FEATURE_REQUESTS.md`: + +```markdown +## [FEAT-YYYYMMDD-XXX] capability_name + +**Logged**: ISO-8601 timestamp +**Priority**: medium +**Status**: pending +**Area**: frontend | backend | infra | tests | docs | config + +### Requested Capability +What the user wanted to do + +### User Context +Why they needed it, what problem they're solving + +### Complexity Estimate +simple | medium | complex + +### Suggested Implementation +How this could be built, what it might extend + +### Metadata +- Frequency: first_time | recurring +- Related Features: existing_feature_name + +--- +``` + +## ID Generation + +Format: `TYPE-YYYYMMDD-XXX` +- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature) +- YYYYMMDD: Current date +- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`) + +Examples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002` + +## Resolving Entries + +When an issue is fixed, update the entry: + +1. Change `**Status**: pending` → `**Status**: resolved` +2. Add resolution block after Metadata: + +```markdown +### Resolution +- **Resolved**: 2025-01-16T09:00:00Z +- **Commit/PR**: abc123 or #42 +- **Notes**: Brief description of what was done +``` + +Other status values: +- `in_progress` - Actively being worked on +- `wont_fix` - Decided not to address (add reason in Resolution notes) +- `promoted` - Elevated to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md + +## Promoting to Project Memory + +When a learning is broadly applicable (not a one-off fix), promote it to permanent project memory. + +### When to Promote + +- Learning applies across multiple files/features +- Knowledge any contributor (human or AI) should know +- Prevents recurring mistakes +- Documents project-specific conventions + +### Promotion Targets + +| Target | What Belongs There | +|--------|-------------------| +| `CLAUDE.md` | Project facts, conventions, gotchas for all Claude interactions | +| `AGENTS.md` | Agent-specific workflows, tool usage patterns, automation rules | +| `.github/copilot-instructions.md` | Project context and conventions for GitHub Copilot | +| `SOUL.md` | Behavioral guidelines, communication style, principles (clawdbot) | +| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas (clawdbot) | + +### How to Promote + +1. **Distill** the learning into a concise rule or fact +2. **Add** to appropriate section in target file (create file if needed) +3. **Update** original entry: + - Change `**Status**: pending` → `**Status**: promoted` + - Add `**Promoted**: CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md` + +### Promotion Examples + +**Learning** (verbose): +> Project uses pnpm workspaces. Attempted `npm install` but failed. +> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`. + +**In CLAUDE.md** (concise): +```markdown +## Build & Dependencies +- Package manager: pnpm (not npm) - use `pnpm install` +``` + +**Learning** (verbose): +> When modifying API endpoints, must regenerate TypeScript client. +> Forgetting this causes type mismatches at runtime. + +**In AGENTS.md** (actionable): +```markdown +## After API Changes +1. Regenerate client: `pnpm run generate:api` +2. Check for type errors: `pnpm tsc --noEmit` +``` + +## Recurring Pattern Detection + +If logging something similar to an existing entry: + +1. **Search first**: `grep -r "keyword" .learnings/` +2. **Link entries**: Add `**See Also**: ERR-20250110-001` in Metadata +3. **Bump priority** if issue keeps recurring +4. **Consider systemic fix**: Recurring issues often indicate: + - Missing documentation (→ promote to CLAUDE.md or .github/copilot-instructions.md) + - Missing automation (→ add to AGENTS.md) + - Architectural problem (→ create tech debt ticket) + +## Periodic Review + +Review `.learnings/` at natural breakpoints: + +### When to Review +- Before starting a new major task +- After completing a feature +- When working in an area with past learnings +- Weekly during active development + +### Quick Status Check +```bash +# Count pending items +grep -h "Status\*\*: pending" .learnings/*.md | wc -l + +# List pending high-priority items +grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \[" + +# Find learnings for a specific area +grep -l "Area\*\*: backend" .learnings/*.md +``` + +### Review Actions +- Resolve fixed items +- Promote applicable learnings +- Link related entries +- Escalate recurring issues + +## Detection Triggers + +Automatically log when you notice: + +**Corrections** (→ learning with `correction` category): +- "No, that's not right..." +- "Actually, it should be..." +- "You're wrong about..." +- "That's outdated..." + +**Feature Requests** (→ feature request): +- "Can you also..." +- "I wish you could..." +- "Is there a way to..." +- "Why can't you..." + +**Knowledge Gaps** (→ learning with `knowledge_gap` category): +- User provides information you didn't know +- Documentation you referenced is outdated +- API behavior differs from your understanding + +**Errors** (→ error entry): +- Command returns non-zero exit code +- Exception or stack trace +- Unexpected output or behavior +- Timeout or connection failure + +## Priority Guidelines + +| Priority | When to Use | +|----------|-------------| +| `critical` | Blocks core functionality, data loss risk, security issue | +| `high` | Significant impact, affects common workflows, recurring issue | +| `medium` | Moderate impact, workaround exists | +| `low` | Minor inconvenience, edge case, nice-to-have | + +## Area Tags + +Use to filter learnings by codebase region: + +| Area | Scope | +|------|-------| +| `frontend` | UI, components, client-side code | +| `backend` | API, services, server-side code | +| `infra` | CI/CD, deployment, Docker, cloud | +| `tests` | Test files, testing utilities, coverage | +| `docs` | Documentation, comments, READMEs | +| `config` | Configuration files, environment, settings | + +## Best Practices + +1. **Log immediately** - context is freshest right after the issue +2. **Be specific** - future agents need to understand quickly +3. **Include reproduction steps** - especially for errors +4. **Link related files** - makes fixes easier +5. **Suggest concrete fixes** - not just "investigate" +6. **Use consistent categories** - enables filtering +7. **Promote aggressively** - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md +8. **Review regularly** - stale learnings lose value + +## Gitignore Options + +**Keep learnings local** (per-developer): +```gitignore +.learnings/ +``` + +**Track learnings in repo** (team-wide): +Don't add to .gitignore - learnings become shared knowledge. + +**Hybrid** (track templates, ignore entries): +```gitignore +.learnings/*.md +!.learnings/.gitkeep +``` + +## Hook Integration + +Enable automatic reminders through agent hooks. This is **opt-in** - you must explicitly configure hooks. + +### Quick Setup (Claude Code / Codex) + +Create `.claude/settings.json` in your project: + +```json +{ + "hooks": { + "UserPromptSubmit": [{ + "matcher": "", + "hooks": [{ + "type": "command", + "command": "./skills/self-improvement/scripts/activator.sh" + }] + }] + } +} +``` + +This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead). + +### Full Setup (With Error Detection) + +```json +{ + "hooks": { + "UserPromptSubmit": [{ + "matcher": "", + "hooks": [{ + "type": "command", + "command": "./skills/self-improvement/scripts/activator.sh" + }] + }], + "PostToolUse": [{ + "matcher": "Bash", + "hooks": [{ + "type": "command", + "command": "./skills/self-improvement/scripts/error-detector.sh" + }] + }] + } +} +``` + +### Available Hook Scripts + +| Script | Hook Type | Purpose | +|--------|-----------|---------| +| `scripts/activator.sh` | UserPromptSubmit | Reminds to evaluate learnings after tasks | +| `scripts/error-detector.sh` | PostToolUse (Bash) | Triggers on command errors | + +See `references/hooks-setup.md` for detailed configuration and troubleshooting. + +## Automatic Skill Extraction + +When a learning is valuable enough to become a reusable skill, extract it using the provided helper. + +### Skill Extraction Criteria + +A learning qualifies for skill extraction when ANY of these apply: + +| Criterion | Description | +|-----------|-------------| +| **Recurring** | Has `See Also` links to 2+ similar issues | +| **Verified** | Status is `resolved` with working fix | +| **Non-obvious** | Required actual debugging/investigation to discover | +| **Broadly applicable** | Not project-specific; useful across codebases | +| **User-flagged** | User says "save this as a skill" or similar | + +### Extraction Workflow + +1. **Identify candidate**: Learning meets extraction criteria +2. **Run helper** (or create manually): + ```bash + ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run + ./skills/self-improvement/scripts/extract-skill.sh skill-name + ``` +3. **Customize SKILL.md**: Fill in template with learning content +4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path` +5. **Verify**: Read skill in fresh session to ensure it's self-contained + +### Manual Extraction + +If you prefer manual creation: + +1. Create `skills//SKILL.md` +2. Use template from `assets/SKILL-TEMPLATE.md` +3. Follow [Agent Skills spec](https://agentskills.io/specification): + - YAML frontmatter with `name` and `description` + - Name must match folder name + - No README.md inside skill folder + +### Extraction Detection Triggers + +Watch for these signals that a learning should become a skill: + +**In conversation:** +- "Save this as a skill" +- "I keep running into this" +- "This would be useful for other projects" +- "Remember this pattern" + +**In learning entries:** +- Multiple `See Also` links (recurring issue) +- High priority + resolved status +- Category: `best_practice` with broad applicability +- User feedback praising the solution + +### Skill Quality Gates + +Before extraction, verify: + +- [ ] Solution is tested and working +- [ ] Description is clear without original context +- [ ] Code examples are self-contained +- [ ] No project-specific hardcoded values +- [ ] Follows skill naming conventions (lowercase, hyphens) + +## Multi-Agent Support + +This skill works across different AI coding agents with agent-specific activation. + +### Claude Code + +**Activation**: Hooks (UserPromptSubmit, PostToolUse) +**Setup**: `.claude/settings.json` with hook configuration +**Detection**: Automatic via hook scripts + +### Codex CLI + +**Activation**: Hooks (same pattern as Claude Code) +**Setup**: `.codex/settings.json` with hook configuration +**Detection**: Automatic via hook scripts + +### GitHub Copilot + +**Activation**: Manual (no hook support) +**Setup**: Add to `.github/copilot-instructions.md`: + +```markdown +## Self-Improvement + +After solving non-obvious issues, consider logging to `.learnings/`: +1. Use format from self-improvement skill +2. Link related entries with See Also +3. Promote high-value learnings to skills + +Ask in chat: "Should I log this as a learning?" +``` + +**Detection**: Manual review at session end + +### Clawdbot + +**Activation**: Workspace injection + inter-agent messaging +**Setup**: Configure workspace path in `~/.clawdbot/clawdbot.json` +**Detection**: Via session tools and workspace files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`) + +Clawdbot uses a workspace-based model with injected prompt files. See `references/clawdbot-integration.md` for detailed setup. + +### Agent-Agnostic Guidance + +Regardless of agent, apply self-improvement when you: + +1. **Discover something non-obvious** - solution wasn't immediate +2. **Correct yourself** - initial approach was wrong +3. **Learn project conventions** - discovered undocumented patterns +4. **Hit unexpected errors** - especially if diagnosis was difficult +5. **Find better approaches** - improved on your original solution + +### Copilot Chat Integration + +For Copilot users, add this to your prompts when relevant: + +> After completing this task, evaluate if any learnings should be logged to `.learnings/` using the self-improvement skill format. + +Or use quick prompts: +- "Log this to learnings" +- "Create a skill from this solution" +- "Check .learnings/ for related issues" + +## Clawdbot Integration + +Clawdbot uses workspace-based prompt injection with specialized files for different concerns. + +### Workspace Structure + +``` +~/clawd/ # Default workspace (configurable) +├── AGENTS.md # Multi-agent workflows, delegation patterns +├── SOUL.md # Behavioral guidelines, communication style +├── TOOLS.md # Tool capabilities, MCP integrations +└── sessions/ # Session transcripts (auto-managed) +``` + +### Clawdbot Promotion Targets + +| Learning Type | Promote To | Example | +|--------------|------------|---------| +| Agent coordination | `AGENTS.md` | "Delegate file searches to explore agent" | +| Communication style | `SOUL.md` | "Be concise, avoid disclaimers" | +| Tool gotchas | `TOOLS.md` | "MCP server X requires auth refresh" | +| Project facts | `CLAUDE.md` | Standard project conventions | + +### Inter-Agent Learning + +Clawdbot supports session-based communication: +- **sessions_list** - See active/recent sessions +- **sessions_history** - Read transcript from another session +- **sessions_send** - Send message to another session + +### Hybrid Setup (Claude Code + Clawdbot) + +When using both: +1. Keep `.learnings/` for project-specific learnings +2. Use clawdbot workspace files for cross-project patterns +3. Sync high-value learnings to both systems + +See `references/clawdbot-integration.md` for complete setup, promotion formats, and troubleshooting. diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..81c36ac --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn73971w6eqrwamn4ajdnv953h7zygkr", + "slug": "self-improving-agent-1-0-2", + "version": "1.0.0", + "publishedAt": 1769436497535 +} \ No newline at end of file diff --git a/assets/LEARNINGS.md b/assets/LEARNINGS.md new file mode 100644 index 0000000..6993f9b --- /dev/null +++ b/assets/LEARNINGS.md @@ -0,0 +1,45 @@ +# Learnings + +Corrections, insights, and knowledge gaps captured during development. + +**Categories**: correction | insight | knowledge_gap | best_practice +**Areas**: frontend | backend | infra | tests | docs | config +**Statuses**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill + +## Status Definitions + +| Status | Meaning | +|--------|---------| +| `pending` | Not yet addressed | +| `in_progress` | Actively being worked on | +| `resolved` | Issue fixed or knowledge integrated | +| `wont_fix` | Decided not to address (reason in Resolution) | +| `promoted` | Elevated to CLAUDE.md, AGENTS.md, or copilot-instructions.md | +| `promoted_to_skill` | Extracted as a reusable skill | + +## Skill Extraction Fields + +When a learning is promoted to a skill, add these fields: + +```markdown +**Status**: promoted_to_skill +**Skill-Path**: skills/skill-name +``` + +Example: +```markdown +## [LRN-20250115-001] best_practice + +**Logged**: 2025-01-15T10:00:00Z +**Priority**: high +**Status**: promoted_to_skill +**Skill-Path**: skills/docker-m1-fixes +**Area**: infra + +### Summary +Docker build fails on Apple Silicon due to platform mismatch +... +``` + +--- + diff --git a/assets/SKILL-TEMPLATE.md b/assets/SKILL-TEMPLATE.md new file mode 100644 index 0000000..0162134 --- /dev/null +++ b/assets/SKILL-TEMPLATE.md @@ -0,0 +1,177 @@ +# Skill Template + +Template for creating skills extracted from learnings. Copy and customize. + +--- + +## SKILL.md Template + +```markdown +--- +name: skill-name-here +description: "Concise description of when and why to use this skill. Include trigger conditions." +--- + +# Skill Name + +Brief introduction explaining the problem this skill solves and its origin. + +## Quick Reference + +| Situation | Action | +|-----------|--------| +| [Trigger 1] | [Action 1] | +| [Trigger 2] | [Action 2] | + +## Background + +Why this knowledge matters. What problems it prevents. Context from the original learning. + +## Solution + +### Step-by-Step + +1. First step with code or command +2. Second step +3. Verification step + +### Code Example + +\`\`\`language +// Example code demonstrating the solution +\`\`\` + +## Common Variations + +- **Variation A**: Description and how to handle +- **Variation B**: Description and how to handle + +## Gotchas + +- Warning or common mistake #1 +- Warning or common mistake #2 + +## Related + +- Link to related documentation +- Link to related skill + +## Source + +Extracted from learning entry. +- **Learning ID**: LRN-YYYYMMDD-XXX +- **Original Category**: correction | insight | knowledge_gap | best_practice +- **Extraction Date**: YYYY-MM-DD +``` + +--- + +## Minimal Template + +For simple skills that don't need all sections: + +```markdown +--- +name: skill-name-here +description: "What this skill does and when to use it." +--- + +# Skill Name + +[Problem statement in one sentence] + +## Solution + +[Direct solution with code/commands] + +## Source + +- Learning ID: LRN-YYYYMMDD-XXX +``` + +--- + +## Template with Scripts + +For skills that include executable helpers: + +```markdown +--- +name: skill-name-here +description: "What this skill does and when to use it." +--- + +# Skill Name + +[Introduction] + +## Quick Reference + +| Command | Purpose | +|---------|---------| +| `./scripts/helper.sh` | [What it does] | +| `./scripts/validate.sh` | [What it does] | + +## Usage + +### Automated (Recommended) + +\`\`\`bash +./skills/skill-name/scripts/helper.sh [args] +\`\`\` + +### Manual Steps + +1. Step one +2. Step two + +## Scripts + +| Script | Description | +|--------|-------------| +| `scripts/helper.sh` | Main utility | +| `scripts/validate.sh` | Validation checker | + +## Source + +- Learning ID: LRN-YYYYMMDD-XXX +``` + +--- + +## Naming Conventions + +- **Skill name**: lowercase, hyphens for spaces + - Good: `docker-m1-fixes`, `api-timeout-patterns` + - Bad: `Docker_M1_Fixes`, `APITimeoutPatterns` + +- **Description**: Start with action verb, mention trigger + - Good: "Handles Docker build failures on Apple Silicon. Use when builds fail with platform mismatch." + - Bad: "Docker stuff" + +- **Files**: + - `SKILL.md` - Required, main documentation + - `scripts/` - Optional, executable code + - `references/` - Optional, detailed docs + - `assets/` - Optional, templates + +--- + +## Extraction Checklist + +Before creating a skill from a learning: + +- [ ] Learning is verified (status: resolved) +- [ ] Solution is broadly applicable (not one-off) +- [ ] Content is complete (has all needed context) +- [ ] Name follows conventions +- [ ] Description is concise but informative +- [ ] Quick Reference table is actionable +- [ ] Code examples are tested +- [ ] Source learning ID is recorded + +After creating: + +- [ ] Update original learning with `promoted_to_skill` status +- [ ] Add `Skill-Path: skills/skill-name` to learning metadata +- [ ] Test skill by reading it in a fresh session diff --git a/references/clawdbot-integration.md b/references/clawdbot-integration.md new file mode 100644 index 0000000..b371162 --- /dev/null +++ b/references/clawdbot-integration.md @@ -0,0 +1,311 @@ +# Clawdbot Integration Guide + +Complete setup and usage guide for integrating the self-improvement skill with Clawdbot's distributed learning model. + +## Overview + +Clawdbot is a terminal-based AI coding assistant that uses workspace-based prompt injection. Unlike Claude Code's hook system, Clawdbot injects context from workspace files at session start and supports inter-agent communication. + +## Architecture Comparison + +| Feature | Claude Code | Clawdbot | +|---------|------------|----------| +| Learning storage | `.learnings/` in project | Workspace files (`~/clawd/`) | +| Activation | Hooks (UserPromptSubmit) | Workspace injection at start | +| Promotion targets | `CLAUDE.md`, `AGENTS.md` | `SOUL.md`, `TOOLS.md`, `AGENTS.md` | +| Inter-agent comms | Not built-in | `sessions_*` tools | +| Skill registry | Manual / agentskills.io | ClawdHub integration | + +## Workspace Setup + +### Default Structure + +``` +~/clawd/ # Configurable via ~/.clawdbot/clawdbot.json +├── AGENTS.md # Multi-agent coordination patterns +├── SOUL.md # Behavioral guidelines and personality +├── TOOLS.md # Tool capabilities and MCP gotchas +├── skills/ # ClawdHub skills cache +│ └── / +│ └── SKILL.md +└── sessions/ # Auto-managed session transcripts + └── .jsonl +``` + +### Configuration + +Edit `~/.clawdbot/clawdbot.json`: + +```json +{ + "workspace": "~/clawd", + "model": "claude-sonnet-4-20250514", + "inject_files": ["AGENTS.md", "SOUL.md", "TOOLS.md"], + "session_history": true +} +``` + +## Injected Prompt Files + +### AGENTS.md + +Purpose: Multi-agent workflows and delegation patterns. + +```markdown +# Agent Coordination + +## Delegation Rules +- Use explore agent for open-ended codebase questions +- Use research-agent for external documentation lookup +- Use Plan agent before complex implementations + +## Session Handoff +When delegating to another session: +1. Provide full context in the handoff message +2. Include relevant file paths +3. Specify expected output format +``` + +### SOUL.md + +Purpose: Behavioral guidelines and communication style. + +```markdown +# Behavioral Guidelines + +## Communication Style +- Be direct and concise +- Avoid unnecessary caveats and disclaimers +- Use technical language appropriate to context + +## Decision Making +- Prefer simple solutions over clever ones +- Ask clarifying questions early +- Explain trade-offs when presenting options + +## Error Handling +- Admit mistakes promptly +- Provide corrected information immediately +- Log significant errors to learnings +``` + +### TOOLS.md + +Purpose: Tool capabilities, MCP server knowledge, integration gotchas. + +```markdown +# Tool Knowledge + +## MCP Servers + +### atlassian +- Use `search` for general queries across Jira/Confluence +- Only use `searchJiraIssuesUsingJql` when JQL syntax is explicitly needed +- CloudId can be extracted from URLs (tool handles conversion) +- Page IDs are in URL path: `/pages/123456789/` + +### leanix +- Use external_id (not internal id) for lookups +- expand_teams/expand_apps for nested data + +## Built-in Tools + +### Bash +- Prefer specialized tools over bash (Read over cat, Glob over find) +- Use for git operations, npm/pnpm, docker commands + +### Task +- Use explore agent for codebase questions +- Use research-agent for external docs +``` + +## Learning Workflow + +### Capturing Learnings + +1. **In-session**: Log to `.learnings/` as usual (project-specific) +2. **Cross-project**: Promote to workspace files (clawdbot) + +### Promotion Decision Tree + +``` +Is the learning project-specific? +├── Yes → Promote to CLAUDE.md or .learnings/ +└── No → Is it behavioral/style-related? + ├── Yes → Promote to SOUL.md + └── No → Is it tool/MCP-related? + ├── Yes → Promote to TOOLS.md + └── No → Promote to AGENTS.md (workflow) +``` + +### Promotion Format Examples + +**From learning:** +> MCP atlassian server: search tool is for general queries. Only use JQL/CQL tools when user explicitly mentions JQL or CQL syntax. + +**To TOOLS.md:** +```markdown +### atlassian +- `search`: Use for general queries (default) +- `searchJiraIssuesUsingJql`: Only when JQL explicitly requested +- `searchConfluenceUsingCql`: Only when CQL explicitly requested +``` + +## Inter-Agent Communication + +Clawdbot provides tools for cross-session communication: + +### sessions_list + +View active and recent sessions: +``` +sessions_list --active +sessions_list --recent 10 +``` + +### sessions_history + +Read transcript from another session: +``` +sessions_history --session --last 50 +``` + +### sessions_send + +Send message to another session: +``` +sessions_send --to --message "Learning: API requires X-Custom-Header" +``` + +### Learning Sharing Pattern + +When discovering something valuable in session A: + +1. Check if other sessions are working on related code: + ``` + sessions_list --active + ``` + +2. Share the learning: + ``` + sessions_send --to session-b --message "FYI: Discovered that the auth API requires refresh tokens every 30min" + ``` + +3. Log to workspace file if broadly applicable: + - Edit `~/clawd/TOOLS.md` or appropriate file + +## ClawdHub Integration + +ClawdHub is Clawdbot's skill registry (similar to agentskills.io). + +### Installing Skills + +```bash +clawd skill install +``` + +Skills are cached in `~/clawd/skills/`. + +### Publishing Skills + +1. Create skill following agentskills.io spec +2. Register with ClawdHub +3. Skills become available to all Clawdbot users + +### Skill Compatibility + +Skills from this repo are compatible with: +- Claude Code (via hooks) +- Codex CLI (via hooks) +- Clawdbot (via ClawdHub) +- GitHub Copilot (via manual setup) + +## Hybrid Setup: Claude Code + Clawdbot + +When using both tools on the same codebase: + +### Recommended Division + +| Concern | Where to Store | +|---------|---------------| +| Project conventions | `CLAUDE.md` (in repo) | +| Project learnings | `.learnings/` (in repo) | +| Personal preferences | `SOUL.md` (clawdbot workspace) | +| Tool knowledge | `TOOLS.md` (clawdbot workspace) | +| Cross-project workflows | `AGENTS.md` (clawdbot workspace) | + +### Sync Strategy + +High-value learnings should exist in both: + +1. Log to `.learnings/` first (project context) +2. If broadly applicable, also add to clawdbot workspace +3. Use consistent formatting for easy grep + +### Example Dual Promotion + +Learning: "Playwright tests require --headed flag for debugging" + +**In `.learnings/LEARNINGS.md`:** +```markdown +## [LRN-20250126-001] correction + +**Status**: promoted +**Promoted**: CLAUDE.md, TOOLS.md (clawdbot) + +### Summary +Playwright tests require --headed flag for visual debugging + +### Details +... +``` + +**In `CLAUDE.md`:** +```markdown +## Testing +- Playwright debugging: use `--headed` flag +``` + +**In `~/clawd/TOOLS.md`:** +```markdown +## Playwright +- Debug mode: `npx playwright test --headed` +- Trace viewer: `npx playwright show-trace trace.zip` +``` + +## Detection Triggers for Clawdbot + +### Standard Triggers (same as Claude Code) +- User corrections +- Command failures +- API errors +- Knowledge gaps + +### Clawdbot-Specific Triggers + +| Trigger | Action | +|---------|--------| +| MCP server error | Log to TOOLS.md with server name | +| Session handoff confusion | Log to AGENTS.md with delegation pattern | +| Model behavior surprise | Log to SOUL.md with expected vs actual | +| ClawdHub skill issue | Log to TOOLS.md or report upstream | + +## Troubleshooting + +### Workspace files not injected + +Check `~/.clawdbot/clawdbot.json`: +- Verify `workspace` path exists +- Verify `inject_files` includes desired files + +### Session communication fails + +- Verify target session is active: `sessions_list --active` +- Check session ID is correct +- Session may have ended + +### Learning not persisting + +Clawdbot doesn't auto-persist learnings. You must: +1. Explicitly write to workspace files +2. Or use `.learnings/` for project-specific storage diff --git a/references/examples.md b/references/examples.md new file mode 100644 index 0000000..1c1db15 --- /dev/null +++ b/references/examples.md @@ -0,0 +1,374 @@ +# Entry Examples + +Concrete examples of well-formatted entries with all fields. + +## Learning: Correction + +```markdown +## [LRN-20250115-001] correction + +**Logged**: 2025-01-15T10:30:00Z +**Priority**: high +**Status**: pending +**Area**: tests + +### Summary +Incorrectly assumed pytest fixtures are scoped to function by default + +### Details +When writing test fixtures, I assumed all fixtures were function-scoped. +User corrected that while function scope is the default, the codebase +convention uses module-scoped fixtures for database connections to +improve test performance. + +### Suggested Action +When creating fixtures that involve expensive setup (DB, network), +check existing fixtures for scope patterns before defaulting to function scope. + +### Metadata +- Source: user_feedback +- Related Files: tests/conftest.py +- Tags: pytest, testing, fixtures + +--- +``` + +## Learning: Knowledge Gap (Resolved) + +```markdown +## [LRN-20250115-002] knowledge_gap + +**Logged**: 2025-01-15T14:22:00Z +**Priority**: medium +**Status**: resolved +**Area**: config + +### Summary +Project uses pnpm not npm for package management + +### Details +Attempted to run `npm install` but project uses pnpm workspaces. +Lock file is `pnpm-lock.yaml`, not `package-lock.json`. + +### Suggested Action +Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm. +Use `pnpm install` for this project. + +### Metadata +- Source: error +- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml +- Tags: package-manager, pnpm, setup + +### Resolution +- **Resolved**: 2025-01-15T14:30:00Z +- **Commit/PR**: N/A - knowledge update +- **Notes**: Added to CLAUDE.md for future reference + +--- +``` + +## Learning: Promoted to CLAUDE.md + +```markdown +## [LRN-20250115-003] best_practice + +**Logged**: 2025-01-15T16:00:00Z +**Priority**: high +**Status**: promoted +**Promoted**: CLAUDE.md +**Area**: backend + +### Summary +API responses must include correlation ID from request headers + +### Details +All API responses should echo back the X-Correlation-ID header from +the request. This is required for distributed tracing. Responses +without this header break the observability pipeline. + +### Suggested Action +Always include correlation ID passthrough in API handlers. + +### Metadata +- Source: user_feedback +- Related Files: src/middleware/correlation.ts +- Tags: api, observability, tracing + +--- +``` + +## Learning: Promoted to AGENTS.md + +```markdown +## [LRN-20250116-001] best_practice + +**Logged**: 2025-01-16T09:00:00Z +**Priority**: high +**Status**: promoted +**Promoted**: AGENTS.md +**Area**: backend + +### Summary +Must regenerate API client after OpenAPI spec changes + +### Details +When modifying API endpoints, the TypeScript client must be regenerated. +Forgetting this causes type mismatches that only appear at runtime. +The generate script also runs validation. + +### Suggested Action +Add to agent workflow: after any API changes, run `pnpm run generate:api`. + +### Metadata +- Source: error +- Related Files: openapi.yaml, src/client/api.ts +- Tags: api, codegen, typescript + +--- +``` + +## Error Entry + +```markdown +## [ERR-20250115-A3F] docker_build + +**Logged**: 2025-01-15T09:15:00Z +**Priority**: high +**Status**: pending +**Area**: infra + +### Summary +Docker build fails on M1 Mac due to platform mismatch + +### Error +``` +error: failed to solve: python:3.11-slim: no match for platform linux/arm64 +``` + +### Context +- Command: `docker build -t myapp .` +- Dockerfile uses `FROM python:3.11-slim` +- Running on Apple Silicon (M1/M2) + +### Suggested Fix +Add platform flag: `docker build --platform linux/amd64 -t myapp .` +Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim` + +### Metadata +- Reproducible: yes +- Related Files: Dockerfile + +--- +``` + +## Error Entry: Recurring Issue + +```markdown +## [ERR-20250120-B2C] api_timeout + +**Logged**: 2025-01-20T11:30:00Z +**Priority**: critical +**Status**: pending +**Area**: backend + +### Summary +Third-party payment API timeout during checkout + +### Error +``` +TimeoutError: Request to payments.example.com timed out after 30000ms +``` + +### Context +- Command: POST /api/checkout +- Timeout set to 30s +- Occurs during peak hours (lunch, evening) + +### Suggested Fix +Implement retry with exponential backoff. Consider circuit breaker pattern. + +### Metadata +- Reproducible: yes (during peak hours) +- Related Files: src/services/payment.ts +- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W + +--- +``` + +## Feature Request + +```markdown +## [FEAT-20250115-001] export_to_csv + +**Logged**: 2025-01-15T16:45:00Z +**Priority**: medium +**Status**: pending +**Area**: backend + +### Requested Capability +Export analysis results to CSV format + +### User Context +User runs weekly reports and needs to share results with non-technical +stakeholders in Excel. Currently copies output manually. + +### Complexity Estimate +simple + +### Suggested Implementation +Add `--output csv` flag to the analyze command. Use standard csv module. +Could extend existing `--output json` pattern. + +### Metadata +- Frequency: recurring +- Related Features: analyze command, json output + +--- +``` + +## Feature Request: Resolved + +```markdown +## [FEAT-20250110-002] dark_mode + +**Logged**: 2025-01-10T14:00:00Z +**Priority**: low +**Status**: resolved +**Area**: frontend + +### Requested Capability +Dark mode support for the dashboard + +### User Context +User works late hours and finds the bright interface straining. +Several other users have mentioned this informally. + +### Complexity Estimate +medium + +### Suggested Implementation +Use CSS variables for colors. Add toggle in user settings. +Consider system preference detection. + +### Metadata +- Frequency: recurring +- Related Features: user settings, theme system + +### Resolution +- **Resolved**: 2025-01-18T16:00:00Z +- **Commit/PR**: #142 +- **Notes**: Implemented with system preference detection and manual toggle + +--- +``` + +## Learning: Promoted to Skill + +```markdown +## [LRN-20250118-001] best_practice + +**Logged**: 2025-01-18T11:00:00Z +**Priority**: high +**Status**: promoted_to_skill +**Skill-Path**: skills/docker-m1-fixes +**Area**: infra + +### Summary +Docker build fails on Apple Silicon due to platform mismatch + +### Details +When building Docker images on M1/M2 Macs, the build fails because +the base image doesn't have an ARM64 variant. This is a common issue +that affects many developers. + +### Suggested Action +Add `--platform linux/amd64` to docker build command, or use +`FROM --platform=linux/amd64` in Dockerfile. + +### Metadata +- Source: error +- Related Files: Dockerfile +- Tags: docker, arm64, m1, apple-silicon +- See Also: ERR-20250115-A3F, ERR-20250117-B2D + +--- +``` + +## Extracted Skill Example + +When the above learning is extracted as a skill, it becomes: + +**File**: `skills/docker-m1-fixes/SKILL.md` + +```markdown +--- +name: docker-m1-fixes +description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors." +--- + +# Docker M1 Fixes + +Solutions for Docker build issues on Apple Silicon Macs. + +## Quick Reference + +| Error | Fix | +|-------|-----| +| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build | +| Image runs but crashes | Use emulation or find ARM-compatible base | + +## The Problem + +Many Docker base images don't have ARM64 variants. When building on +Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by +default, causing platform mismatch errors. + +## Solutions + +### Option 1: Build Flag (Recommended) + +Add platform flag to your build command: + +\`\`\`bash +docker build --platform linux/amd64 -t myapp . +\`\`\` + +### Option 2: Dockerfile Modification + +Specify platform in the FROM instruction: + +\`\`\`dockerfile +FROM --platform=linux/amd64 python:3.11-slim +\`\`\` + +### Option 3: Docker Compose + +Add platform to your service: + +\`\`\`yaml +services: + app: + platform: linux/amd64 + build: . +\`\`\` + +## Trade-offs + +| Approach | Pros | Cons | +|----------|------|------| +| Build flag | No file changes | Must remember flag | +| Dockerfile | Explicit, versioned | Affects all builds | +| Compose | Convenient for dev | Requires compose | + +## Performance Note + +Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works +for development but may be slower. For production, find ARM-native +alternatives when possible. + +## Source + +- Learning ID: LRN-20250118-001 +- Category: best_practice +- Extraction Date: 2025-01-18 +``` diff --git a/references/hooks-setup.md b/references/hooks-setup.md new file mode 100644 index 0000000..08b5dd1 --- /dev/null +++ b/references/hooks-setup.md @@ -0,0 +1,223 @@ +# Hook Setup Guide + +Configure automatic self-improvement triggers for AI coding agents. + +## Overview + +Hooks enable proactive learning capture by injecting reminders at key moments: +- **UserPromptSubmit**: Reminder after each prompt to evaluate learnings +- **PostToolUse (Bash)**: Error detection when commands fail + +## Claude Code Setup + +### Option 1: Project-Level Configuration + +Create `.claude/settings.json` in your project root: + +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "./skills/self-improvement/scripts/activator.sh" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "./skills/self-improvement/scripts/error-detector.sh" + } + ] + } + ] + } +} +``` + +### Option 2: User-Level Configuration + +Add to `~/.claude/settings.json` for global activation: + +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "~/.claude/skills/self-improvement/scripts/activator.sh" + } + ] + } + ] + } +} +``` + +### Minimal Setup (Activator Only) + +For lower overhead, use only the UserPromptSubmit hook: + +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "./skills/self-improvement/scripts/activator.sh" + } + ] + } + ] + } +} +``` + +## Codex CLI Setup + +Codex uses the same hook system as Claude Code. Create `.codex/settings.json`: + +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "./skills/self-improvement/scripts/activator.sh" + } + ] + } + ] + } +} +``` + +## GitHub Copilot Setup + +Copilot doesn't support hooks directly. Instead, add guidance to `.github/copilot-instructions.md`: + +```markdown +## Self-Improvement + +After completing tasks that involved: +- Debugging non-obvious issues +- Discovering workarounds +- Learning project-specific patterns +- Resolving unexpected errors + +Consider logging the learning to `.learnings/` using the format from the self-improvement skill. + +For high-value learnings that would benefit other sessions, consider skill extraction. +``` + +## Verification + +### Test Activator Hook + +1. Enable the hook configuration +2. Start a new Claude Code session +3. Send any prompt +4. Verify you see `` in the context + +### Test Error Detector Hook + +1. Enable PostToolUse hook for Bash +2. Run a command that fails: `ls /nonexistent/path` +3. Verify you see `` reminder + +### Dry Run Extract Script + +```bash +./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run +``` + +Expected output shows the skill scaffold that would be created. + +## Troubleshooting + +### Hook Not Triggering + +1. **Check script permissions**: `chmod +x scripts/*.sh` +2. **Verify path**: Use absolute paths or paths relative to project root +3. **Check settings location**: Project vs user-level settings +4. **Restart session**: Hooks are loaded at session start + +### Permission Denied + +```bash +chmod +x ./skills/self-improvement/scripts/activator.sh +chmod +x ./skills/self-improvement/scripts/error-detector.sh +chmod +x ./skills/self-improvement/scripts/extract-skill.sh +``` + +### Script Not Found + +If using relative paths, ensure you're in the correct directory or use absolute paths: + +```json +{ + "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh" +} +``` + +### Too Much Overhead + +If the activator feels intrusive: + +1. **Use minimal setup**: Only UserPromptSubmit, skip PostToolUse +2. **Add matcher filter**: Only trigger for certain prompts: + +```json +{ + "matcher": "fix|debug|error|issue", + "hooks": [...] +} +``` + +## Hook Output Budget + +The activator is designed to be lightweight: +- **Target**: ~50-100 tokens per activation +- **Content**: Structured reminder, not verbose instructions +- **Format**: XML tags for easy parsing + +If you need to reduce overhead further, you can edit `activator.sh` to output less text. + +## Security Considerations + +- Hook scripts run with the same permissions as Claude Code +- Scripts only output text; they don't modify files or run commands +- Error detector reads `CLAUDE_TOOL_OUTPUT` environment variable +- All scripts are opt-in (you must configure them explicitly) + +## Disabling Hooks + +To temporarily disable without removing configuration: + +1. **Comment out in settings**: +```json +{ + "hooks": { + // "UserPromptSubmit": [...] + } +} +``` + +2. **Or delete the settings file**: Hooks won't run without configuration diff --git a/scripts/activator.sh b/scripts/activator.sh new file mode 100644 index 0000000..29eec22 --- /dev/null +++ b/scripts/activator.sh @@ -0,0 +1,20 @@ +#!/bin/bash +# Self-Improvement Activator Hook +# Triggers on UserPromptSubmit to remind Claude about learning capture +# Keep output minimal (~50-100 tokens) to minimize overhead + +set -e + +# Output reminder as system context +cat << 'EOF' + +After completing this task, evaluate if extractable knowledge emerged: +- Non-obvious solution discovered through investigation? +- Workaround for unexpected behavior? +- Project-specific pattern learned? +- Error required debugging to resolve? + +If yes: Log to .learnings/ using the self-improvement skill format. +If high-value (recurring, broadly applicable): Consider skill extraction. + +EOF diff --git a/scripts/error-detector.sh b/scripts/error-detector.sh new file mode 100644 index 0000000..3c310dd --- /dev/null +++ b/scripts/error-detector.sh @@ -0,0 +1,55 @@ +#!/bin/bash +# Self-Improvement Error Detector Hook +# Triggers on PostToolUse for Bash to detect command failures +# Reads CLAUDE_TOOL_OUTPUT environment variable + +set -e + +# Check if tool output indicates an error +# CLAUDE_TOOL_OUTPUT contains the result of the tool execution +OUTPUT="${CLAUDE_TOOL_OUTPUT:-}" + +# Patterns indicating errors (case-insensitive matching) +ERROR_PATTERNS=( + "error:" + "Error:" + "ERROR:" + "failed" + "FAILED" + "command not found" + "No such file" + "Permission denied" + "fatal:" + "Exception" + "Traceback" + "npm ERR!" + "ModuleNotFoundError" + "SyntaxError" + "TypeError" + "exit code" + "non-zero" +) + +# Check if output contains any error pattern +contains_error=false +for pattern in "${ERROR_PATTERNS[@]}"; do + if [[ "$OUTPUT" == *"$pattern"* ]]; then + contains_error=true + break + fi +done + +# Only output reminder if error detected +if [ "$contains_error" = true ]; then + cat << 'EOF' + +A command error was detected. Consider logging this to .learnings/ERRORS.md if: +- The error was unexpected or non-obvious +- It required investigation to resolve +- It might recur in similar contexts +- The solution could benefit future sessions + +Use the self-improvement skill format: [ERR-YYYYMMDD-XXX] + +EOF +fi diff --git a/scripts/extract-skill.sh b/scripts/extract-skill.sh new file mode 100644 index 0000000..2675924 --- /dev/null +++ b/scripts/extract-skill.sh @@ -0,0 +1,203 @@ +#!/bin/bash +# Skill Extraction Helper +# Creates a new skill from a learning entry +# Usage: ./extract-skill.sh [--dry-run] + +set -e + +# Configuration +SKILLS_DIR="${SKILLS_DIR:-./skills}" +TEMPLATE_DIR="$(dirname "$0")/../assets" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +usage() { + cat << EOF +Usage: $(basename "$0") [options] + +Create a new skill from a learning entry. + +Arguments: + skill-name Name of the skill (lowercase, hyphens for spaces) + +Options: + --dry-run Show what would be created without creating files + --output-dir Override skills directory (default: ./skills) + -h, --help Show this help message + +Examples: + $(basename "$0") docker-m1-fixes + $(basename "$0") api-timeout-patterns --dry-run + $(basename "$0") pnpm-setup --output-dir /path/to/skills + +The skill will be created in: \$SKILLS_DIR// +EOF +} + +log_info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +log_warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $1" >&2 +} + +# Parse arguments +SKILL_NAME="" +DRY_RUN=false + +while [[ $# -gt 0 ]]; do + case $1 in + --dry-run) + DRY_RUN=true + shift + ;; + --output-dir) + SKILLS_DIR="$2" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + -*) + log_error "Unknown option: $1" + usage + exit 1 + ;; + *) + if [ -z "$SKILL_NAME" ]; then + SKILL_NAME="$1" + else + log_error "Unexpected argument: $1" + usage + exit 1 + fi + shift + ;; + esac +done + +# Validate skill name +if [ -z "$SKILL_NAME" ]; then + log_error "Skill name is required" + usage + exit 1 +fi + +# Validate skill name format (lowercase, hyphens, no spaces) +if ! [[ "$SKILL_NAME" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then + log_error "Invalid skill name format. Use lowercase letters, numbers, and hyphens only." + log_error "Examples: 'docker-fixes', 'api-patterns', 'pnpm-setup'" + exit 1 +fi + +SKILL_PATH="$SKILLS_DIR/$SKILL_NAME" + +# Check if skill already exists +if [ -d "$SKILL_PATH" ] && [ "$DRY_RUN" = false ]; then + log_error "Skill already exists: $SKILL_PATH" + log_error "Use a different name or remove the existing skill first." + exit 1 +fi + +# Dry run output +if [ "$DRY_RUN" = true ]; then + log_info "Dry run - would create:" + echo " $SKILL_PATH/" + echo " $SKILL_PATH/SKILL.md" + echo "" + echo "Template content would be:" + echo "---" + cat << TEMPLATE +name: $SKILL_NAME +description: "[TODO: Add a concise description of what this skill does and when to use it]" +--- + +# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1') + +[TODO: Brief introduction explaining the skill's purpose] + +## Quick Reference + +| Situation | Action | +|-----------|--------| +| [Trigger condition] | [What to do] | + +## Usage + +[TODO: Detailed usage instructions] + +## Examples + +[TODO: Add concrete examples] + +## Source Learning + +This skill was extracted from a learning entry. +- Learning ID: [TODO: Add original learning ID] +- Original File: .learnings/LEARNINGS.md +TEMPLATE + echo "---" + exit 0 +fi + +# Create skill directory structure +log_info "Creating skill: $SKILL_NAME" + +mkdir -p "$SKILL_PATH" + +# Create SKILL.md from template +cat > "$SKILL_PATH/SKILL.md" << TEMPLATE +--- +name: $SKILL_NAME +description: "[TODO: Add a concise description of what this skill does and when to use it]" +--- + +# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1') + +[TODO: Brief introduction explaining the skill's purpose] + +## Quick Reference + +| Situation | Action | +|-----------|--------| +| [Trigger condition] | [What to do] | + +## Usage + +[TODO: Detailed usage instructions] + +## Examples + +[TODO: Add concrete examples] + +## Source Learning + +This skill was extracted from a learning entry. +- Learning ID: [TODO: Add original learning ID] +- Original File: .learnings/LEARNINGS.md +TEMPLATE + +log_info "Created: $SKILL_PATH/SKILL.md" + +# Suggest next steps +echo "" +log_info "Skill scaffold created successfully!" +echo "" +echo "Next steps:" +echo " 1. Edit $SKILL_PATH/SKILL.md" +echo " 2. Fill in the TODO sections with content from your learning" +echo " 3. Add references/ folder if you have detailed documentation" +echo " 4. Add scripts/ folder if you have executable code" +echo " 5. Update the original learning entry with:" +echo " **Status**: promoted_to_skill" +echo " **Skill-Path**: skills/$SKILL_NAME"