Initial commit with translated description
This commit is contained in:
552
SKILL.md
Normal file
552
SKILL.md
Normal file
@@ -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-name>/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.
|
||||
6
_meta.json
Normal file
6
_meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"ownerId": "kn73971w6eqrwamn4ajdnv953h7zygkr",
|
||||
"slug": "self-improving-agent-1-0-2",
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1769436497535
|
||||
}
|
||||
45
assets/LEARNINGS.md
Normal file
45
assets/LEARNINGS.md
Normal file
@@ -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
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
177
assets/SKILL-TEMPLATE.md
Normal file
177
assets/SKILL-TEMPLATE.md
Normal file
@@ -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
|
||||
311
references/clawdbot-integration.md
Normal file
311
references/clawdbot-integration.md
Normal file
@@ -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-name>/
|
||||
│ └── SKILL.md
|
||||
└── sessions/ # Auto-managed session transcripts
|
||||
└── <session-id>.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 <session-id> --last 50
|
||||
```
|
||||
|
||||
### sessions_send
|
||||
|
||||
Send message to another session:
|
||||
```
|
||||
sessions_send --to <session-id> --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 <skill-name>
|
||||
```
|
||||
|
||||
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
|
||||
374
references/examples.md
Normal file
374
references/examples.md
Normal file
@@ -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
|
||||
```
|
||||
223
references/hooks-setup.md
Normal file
223
references/hooks-setup.md
Normal file
@@ -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 `<self-improvement-reminder>` 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 `<error-detected>` 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
|
||||
20
scripts/activator.sh
Normal file
20
scripts/activator.sh
Normal file
@@ -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'
|
||||
<self-improvement-reminder>
|
||||
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.
|
||||
</self-improvement-reminder>
|
||||
EOF
|
||||
55
scripts/error-detector.sh
Normal file
55
scripts/error-detector.sh
Normal file
@@ -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'
|
||||
<error-detected>
|
||||
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]
|
||||
</error-detected>
|
||||
EOF
|
||||
fi
|
||||
203
scripts/extract-skill.sh
Normal file
203
scripts/extract-skill.sh
Normal file
@@ -0,0 +1,203 @@
|
||||
#!/bin/bash
|
||||
# Skill Extraction Helper
|
||||
# Creates a new skill from a learning entry
|
||||
# Usage: ./extract-skill.sh <skill-name> [--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") <skill-name> [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/<skill-name>/
|
||||
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"
|
||||
Reference in New Issue
Block a user