commit ec330eed2e5e0562a286eda2a763313aec8d4707 Author: zlei9 Date: Sun Mar 29 13:06:02 2026 +0800 Initial commit with translated description diff --git a/.learnings/ERRORS.md b/.learnings/ERRORS.md new file mode 100644 index 0000000..6bce392 --- /dev/null +++ b/.learnings/ERRORS.md @@ -0,0 +1,5 @@ +# Errors Log + +Command failures, exceptions, and unexpected behaviors. + +--- diff --git a/.learnings/FEATURE_REQUESTS.md b/.learnings/FEATURE_REQUESTS.md new file mode 100644 index 0000000..3527277 --- /dev/null +++ b/.learnings/FEATURE_REQUESTS.md @@ -0,0 +1,5 @@ +# Feature Requests + +Capabilities requested by user that don't currently exist. + +--- diff --git a/.learnings/LEARNINGS.md b/.learnings/LEARNINGS.md new file mode 100644 index 0000000..d31195d --- /dev/null +++ b/.learnings/LEARNINGS.md @@ -0,0 +1,5 @@ +# Learnings Log + +Captured learnings, corrections, and discoveries. Review before major tasks. + +--- diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..63effa9 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,647 @@ +--- +name: self-improvement +description: "捕获学习、错误和更正以实现持续改进。" +metadata: +--- + +# 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` | +| Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` | +| 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` (OpenClaw workspace) | +| Tool gotchas | Promote to `TOOLS.md` (OpenClaw workspace) | +| Behavioral patterns | Promote to `SOUL.md` (OpenClaw workspace) | + +## OpenClaw Setup (Recommended) + +OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading. + +### Installation + +**Via ClawdHub (recommended):** +```bash +clawdhub install self-improving-agent +``` + +**Manual:** +```bash +git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent +``` + +Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement + +### Workspace Structure + +OpenClaw injects these files into every session: + +``` +~/.openclaw/workspace/ +├── AGENTS.md # Multi-agent workflows, delegation patterns +├── SOUL.md # Behavioral guidelines, personality, principles +├── TOOLS.md # Tool capabilities, integration gotchas +├── MEMORY.md # Long-term memory (main session only) +├── memory/ # Daily memory files +│ └── YYYY-MM-DD.md +└── .learnings/ # This skill's log files + ├── LEARNINGS.md + ├── ERRORS.md + └── FEATURE_REQUESTS.md +``` + +### Create Learning Files + +```bash +mkdir -p ~/.openclaw/workspace/.learnings +``` + +Then create the log files (or copy from `assets/`): +- `LEARNINGS.md` — corrections, knowledge gaps, best practices +- `ERRORS.md` — command failures, exceptions +- `FEATURE_REQUESTS.md` — user-requested capabilities + +### Promotion Targets + +When learnings prove broadly applicable, promote them to workspace files: + +| Learning Type | Promote To | Example | +|---------------|------------|---------| +| Behavioral patterns | `SOUL.md` | "Be concise, avoid disclaimers" | +| Workflow improvements | `AGENTS.md` | "Spawn sub-agents for long tasks" | +| Tool gotchas | `TOOLS.md` | "Git push needs auth configured first" | + +### Inter-Session Communication + +OpenClaw provides tools to share learnings across sessions: + +- **sessions_list** — View active/recent sessions +- **sessions_history** — Read another session's transcript +- **sessions_send** — Send a learning to another session +- **sessions_spawn** — Spawn a sub-agent for background work + +### Optional: Enable Hook + +For automatic reminders at session start: + +```bash +# Copy hook to OpenClaw hooks directory +cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement + +# Enable it +openclaw hooks enable self-improvement +``` + +See `references/openclaw-integration.md` for complete details. + +--- + +## Generic Setup (Other Agents) + +For Claude Code, Codex, Copilot, or other agents, create `.learnings/` in your project: + +```bash +mkdir -p .learnings +``` + +Copy templates from `assets/` or create files with headers. + +### Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log learnings. (this is an alternative to hook-based reminders) + +#### Self-Improvement Workflow + +When errors or corrections occur: +1. Log to `.learnings/ERRORS.md`, `LEARNINGS.md`, or `FEATURE_REQUESTS.md` +2. Review and promote broadly applicable learnings to: + - `CLAUDE.md` - project facts and conventions + - `AGENTS.md` - workflows and automation + - `.github/copilot-instructions.md` - Copilot context + +## 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) +- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking) +- Recurrence-Count: 1 (optional) +- First-Seen: 2025-01-15 (optional) +- Last-Seen: 2025-01-15 (optional) + +--- +``` + +### 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 (OpenClaw workspace) | +| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas (OpenClaw workspace) | + +### 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) + +## Simplify & Harden Feed + +Use this workflow to ingest recurring patterns from the `simplify-and-harden` +skill and turn them into durable prompt guidance. + +### Ingestion Workflow + +1. Read `simplify_and_harden.learning_loop.candidates` from the task summary. +2. For each candidate, use `pattern_key` as the stable dedupe key. +3. Search `.learnings/LEARNINGS.md` for an existing entry with that key: + - `grep -n "Pattern-Key: " .learnings/LEARNINGS.md` +4. If found: + - Increment `Recurrence-Count` + - Update `Last-Seen` + - Add `See Also` links to related entries/tasks +5. If not found: + - Create a new `LRN-...` entry + - Set `Source: simplify-and-harden` + - Set `Pattern-Key`, `Recurrence-Count: 1`, and `First-Seen`/`Last-Seen` + +### Promotion Rule (System Prompt Feedback) + +Promote recurring patterns into agent context/system prompt files when all are true: + +- `Recurrence-Count >= 3` +- Seen across at least 2 distinct tasks +- Occurred within a 30-day window + +Promotion targets: +- `CLAUDE.md` +- `AGENTS.md` +- `.github/copilot-instructions.md` +- `SOUL.md` / `TOOLS.md` for OpenClaw workspace-level guidance when applicable + +Write promoted rules as short prevention rules (what to do before/while coding), +not long incident write-ups. + +## 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 + +### OpenClaw + +**Activation**: Workspace injection + inter-agent messaging +**Setup**: See "OpenClaw Setup" section above +**Detection**: Via session tools and workspace files + +### 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" diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..6ef6a3d --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn728s101fdyy0s6kz0g8dw71h81pag5", + "slug": "self-improvement", + "version": "1.0.0", + "publishedAt": 1772443902584 +} \ 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/hooks/openclaw/HOOK.md b/hooks/openclaw/HOOK.md new file mode 100644 index 0000000..df67405 --- /dev/null +++ b/hooks/openclaw/HOOK.md @@ -0,0 +1,23 @@ +--- +name: self-improvement +description: "Injects self-improvement reminder during agent bootstrap" +metadata: {"openclaw":{"emoji":"🧠","events":["agent:bootstrap"]}} +--- + +# Self-Improvement Hook + +Injects a reminder to evaluate learnings during agent bootstrap. + +## What It Does + +- Fires on `agent:bootstrap` (before workspace files are injected) +- Adds a reminder block to check `.learnings/` for relevant entries +- Prompts the agent to log corrections, errors, and discoveries + +## Configuration + +No configuration needed. Enable with: + +```bash +openclaw hooks enable self-improvement +``` diff --git a/hooks/openclaw/handler.js b/hooks/openclaw/handler.js new file mode 100644 index 0000000..73278ea --- /dev/null +++ b/hooks/openclaw/handler.js @@ -0,0 +1,56 @@ +/** + * Self-Improvement Hook for OpenClaw + * + * Injects a reminder to evaluate learnings during agent bootstrap. + * Fires on agent:bootstrap event before workspace files are injected. + */ + +const REMINDER_CONTENT = ` +## Self-Improvement Reminder + +After completing tasks, evaluate if any learnings should be captured: + +**Log when:** +- User corrects you → \`.learnings/LEARNINGS.md\` +- Command/operation fails → \`.learnings/ERRORS.md\` +- User wants missing capability → \`.learnings/FEATURE_REQUESTS.md\` +- You discover your knowledge was wrong → \`.learnings/LEARNINGS.md\` +- You find a better approach → \`.learnings/LEARNINGS.md\` + +**Promote when pattern is proven:** +- Behavioral patterns → \`SOUL.md\` +- Workflow improvements → \`AGENTS.md\` +- Tool gotchas → \`TOOLS.md\` + +Keep entries simple: date, title, what happened, what to do differently. +`.trim(); + +const handler = async (event) => { + // Safety checks for event structure + if (!event || typeof event !== 'object') { + return; + } + + // Only handle agent:bootstrap events + if (event.type !== 'agent' || event.action !== 'bootstrap') { + return; + } + + // Safety check for context + if (!event.context || typeof event.context !== 'object') { + return; + } + + // Inject the reminder as a virtual bootstrap file + // Check that bootstrapFiles is an array before pushing + if (Array.isArray(event.context.bootstrapFiles)) { + event.context.bootstrapFiles.push({ + path: 'SELF_IMPROVEMENT_REMINDER.md', + content: REMINDER_CONTENT, + virtual: true, + }); + } +}; + +module.exports = handler; +module.exports.default = handler; diff --git a/hooks/openclaw/handler.ts b/hooks/openclaw/handler.ts new file mode 100644 index 0000000..9ec23f3 --- /dev/null +++ b/hooks/openclaw/handler.ts @@ -0,0 +1,62 @@ +/** + * Self-Improvement Hook for OpenClaw + * + * Injects a reminder to evaluate learnings during agent bootstrap. + * Fires on agent:bootstrap event before workspace files are injected. + */ + +import type { HookHandler } from 'openclaw/hooks'; + +const REMINDER_CONTENT = `## Self-Improvement Reminder + +After completing tasks, evaluate if any learnings should be captured: + +**Log when:** +- User corrects you → \`.learnings/LEARNINGS.md\` +- Command/operation fails → \`.learnings/ERRORS.md\` +- User wants missing capability → \`.learnings/FEATURE_REQUESTS.md\` +- You discover your knowledge was wrong → \`.learnings/LEARNINGS.md\` +- You find a better approach → \`.learnings/LEARNINGS.md\` + +**Promote when pattern is proven:** +- Behavioral patterns → \`SOUL.md\` +- Workflow improvements → \`AGENTS.md\` +- Tool gotchas → \`TOOLS.md\` + +Keep entries simple: date, title, what happened, what to do differently.`; + +const handler: HookHandler = async (event) => { + // Safety checks for event structure + if (!event || typeof event !== 'object') { + return; + } + + // Only handle agent:bootstrap events + if (event.type !== 'agent' || event.action !== 'bootstrap') { + return; + } + + // Safety check for context + if (!event.context || typeof event.context !== 'object') { + return; + } + + // Skip sub-agent sessions to avoid bootstrap issues + // Sub-agents have sessionKey patterns like "agent:main:subagent:..." + const sessionKey = event.sessionKey || ''; + if (sessionKey.includes(':subagent:')) { + return; + } + + // Inject the reminder as a virtual bootstrap file + // Check that bootstrapFiles is an array before pushing + if (Array.isArray(event.context.bootstrapFiles)) { + event.context.bootstrapFiles.push({ + path: 'SELF_IMPROVEMENT_REMINDER.md', + content: REMINDER_CONTENT, + virtual: true, + }); + } +}; + +export default handler; 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/references/openclaw-integration.md b/references/openclaw-integration.md new file mode 100644 index 0000000..09f0193 --- /dev/null +++ b/references/openclaw-integration.md @@ -0,0 +1,248 @@ +# OpenClaw Integration + +Complete setup and usage guide for integrating the self-improvement skill with OpenClaw. + +## Overview + +OpenClaw uses workspace-based prompt injection combined with event-driven hooks. Context is injected from workspace files at session start, and hooks can trigger on lifecycle events. + +## Workspace Structure + +``` +~/.openclaw/ +├── workspace/ # Working directory +│ ├── AGENTS.md # Multi-agent coordination patterns +│ ├── SOUL.md # Behavioral guidelines and personality +│ ├── TOOLS.md # Tool capabilities and gotchas +│ ├── MEMORY.md # Long-term memory (main session only) +│ └── memory/ # Daily memory files +│ └── YYYY-MM-DD.md +├── skills/ # Installed skills +│ └── / +│ └── SKILL.md +└── hooks/ # Custom hooks + └── / + ├── HOOK.md + └── handler.ts +``` + +## Quick Setup + +### 1. Install the Skill + +```bash +clawdhub install self-improving-agent +``` + +Or copy manually: + +```bash +cp -r self-improving-agent ~/.openclaw/skills/ +``` + +### 2. Install the Hook (Optional) + +Copy the hook to OpenClaw's hooks directory: + +```bash +cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement +``` + +Enable the hook: + +```bash +openclaw hooks enable self-improvement +``` + +### 3. Create Learning Files + +Create the `.learnings/` directory in your workspace: + +```bash +mkdir -p ~/.openclaw/workspace/.learnings +``` + +Or in the skill directory: + +```bash +mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings +``` + +## 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 +- Spawn sub-agents for long-running tasks +- Use sessions_send for cross-session communication + +## 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 + +## Error Handling +- Admit mistakes promptly +- Provide corrected information immediately +- Log significant errors to learnings +``` + +### TOOLS.md + +Purpose: Tool capabilities, integration gotchas, local configuration. + +```markdown +# Tool Knowledge + +## Self-Improvement Skill +Log learnings to `.learnings/` for continuous improvement. + +## Local Tools +- Document tool-specific gotchas here +- Note authentication requirements +- Track integration quirks +``` + +## Learning Workflow + +### Capturing Learnings + +1. **In-session**: Log to `.learnings/` as usual +2. **Cross-session**: Promote to workspace files + +### Promotion Decision Tree + +``` +Is the learning project-specific? +├── Yes → Keep in .learnings/ +└── No → Is it behavioral/style-related? + ├── Yes → Promote to SOUL.md + └── No → Is it tool-related? + ├── Yes → Promote to TOOLS.md + └── No → Promote to AGENTS.md (workflow) +``` + +### Promotion Format Examples + +**From learning:** +> Git push to GitHub fails without auth configured - triggers desktop prompt + +**To TOOLS.md:** +```markdown +## Git +- Don't push without confirming auth is configured +- Use `gh auth status` to check GitHub CLI auth +``` + +## Inter-Agent Communication + +OpenClaw provides tools for cross-session communication: + +### sessions_list + +View active and recent sessions: +``` +sessions_list(activeMinutes=30, messageLimit=3) +``` + +### sessions_history + +Read transcript from another session: +``` +sessions_history(sessionKey="session-id", limit=50) +``` + +### sessions_send + +Send message to another session: +``` +sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header") +``` + +### sessions_spawn + +Spawn a background sub-agent: +``` +sessions_spawn(task="Research X and report back", label="research") +``` + +## Available Hook Events + +| Event | When It Fires | +|-------|---------------| +| `agent:bootstrap` | Before workspace files inject | +| `command:new` | When `/new` command issued | +| `command:reset` | When `/reset` command issued | +| `command:stop` | When `/stop` command issued | +| `gateway:startup` | When gateway starts | + +## Detection Triggers + +### Standard Triggers +- User corrections ("No, that's wrong...") +- Command failures (non-zero exit codes) +- API errors +- Knowledge gaps + +### OpenClaw-Specific Triggers + +| Trigger | Action | +|---------|--------| +| Tool call error | Log to TOOLS.md with tool name | +| Session handoff confusion | Log to AGENTS.md with delegation pattern | +| Model behavior surprise | Log to SOUL.md with expected vs actual | +| Skill issue | Log to .learnings/ or report upstream | + +## Verification + +Check hook is registered: + +```bash +openclaw hooks list +``` + +Check skill is loaded: + +```bash +openclaw status +``` + +## Troubleshooting + +### Hook not firing + +1. Ensure hooks enabled in config +2. Restart gateway after config changes +3. Check gateway logs for errors + +### Learnings not persisting + +1. Verify `.learnings/` directory exists +2. Check file permissions +3. Ensure workspace path is configured correctly + +### Skill not loading + +1. Check skill is in skills directory +2. Verify SKILL.md has correct frontmatter +3. Run `openclaw status` to see loaded skills 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..ccae55a --- /dev/null +++ b/scripts/extract-skill.sh @@ -0,0 +1,221 @@ +#!/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" + +# 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 Relative output directory under current path (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 ./skills/custom + +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) + if [ -z "${2:-}" ] || [[ "${2:-}" == -* ]]; then + log_error "--output-dir requires a relative path argument" + usage + exit 1 + fi + 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 + +# Validate output path to avoid writes outside current workspace. +if [[ "$SKILLS_DIR" = /* ]]; then + log_error "Output directory must be a relative path under the current directory." + exit 1 +fi + +if [[ "$SKILLS_DIR" =~ (^|/)\.\.(/|$) ]]; then + log_error "Output directory cannot include '..' path segments." + exit 1 +fi + +SKILLS_DIR="${SKILLS_DIR#./}" +SKILLS_DIR="./$SKILLS_DIR" + +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"