self-improving-agent
自我改进Agent快速参考,按情境对照行动
skillhub install @zcwl/self-improving-agent
README 文档
11,850 字For CI-only execution, use:
安装此Skill请参考SkillHub平台指南
Quick Reference
| Situation | Action |
|---|---|
| Active failure mid-task — agent needs to fix it now | Use self-healing instead (files verified HEAL- to .learnings/HEALS.md) |
| Command/operation failed in the past (not actively healing) | 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 |
| Self-healing Handoff block meets promotion rule (see Promotion Rule below) | Promote the Distilled Rule to CLAUDE.md / AGENTS.md / new skill |
| 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 |
| 工作空间 targets (SOUL.md, TOOLS.md) | See references/skill-platform-integration.md |
Setup
Create .learnings/ directory in project root if it doesn't exist:
mkdir -p .learnings
Copy the file templates from assets/ (LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md) or create files with headers.
Logging Format
Learning Entry
Append to .learnings/LEARNINGS.md:
Error Entry
详细内容已移至
references/detail.md
Feature Request Entry
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:
- Change
Status: pending→Status: resolved - Add resolution block after Metadata:
- **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 onwont_fix- Decided not to address (add reason in Resolution notes)promoted- Elevated to CLAUDE.md, AGENTS.md, or .mdpromotedtoskill- Extracted as a reusable skill (see Automatic Skill Extraction)
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 |
.md | Project context and conventions for GitHub Copilot |
工作空间 targets (SOUL.md, TOOLS.md) are covered in references/skill-platform-integration.md.
How to Promote
- Distill the learning into a concise rule or fact
- Add to appropriate section in target file (create file if needed)
- Update original entry:
- Change
Status: pending→Status: promoted - Add
Promoted: CLAUDE.md,AGENTS.md, or.md
示例
Learning (verbose):
In CLAUDE.md (concise):
- Package manager: pnpm (not npm) - use `pnpm install`
Learning (verbose):
In AGENTS.md (actionable):
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:
- Search first:
grep -r "keyword" .learnings/ - Link entries: Add
See Also: ERR-20250110-001in Metadata - Bump priority if issue keeps recurring
- Consider systemic fix: Recurring issues often indicate:
- Missing documentation (→ promote to CLAUDE.md or .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
- Read
simplifyandharden.learning_loop.candidatesfrom the task summary. - For each candidate, use
pattern_keyas the stable dedupe key. - Search
.learnings/LEARNINGS.mdfor an existing entry with that key:
grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
- If found:
- Increment
Recurrence-Count - Update
Last-Seen - Add
See Alsolinks to related entries/tasks
- If not found:
- Create a new
LRN-...entry - Set
Source: simplify-and-harden - Set
Pattern-Key,Recurrence-Count: 1, andFirst-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.mdAGENTS.md- 工作空间 files when applicable — see
references/skill-platform-integration.md
This three-condition rule is the single promotion threshold for this skill. The Quick Reference row for self-healing Handoff blocks and the aggregator skills (learning-aggregator, learning-aggregator-ci) all use this same rule.
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
grep -h "Status**: pending" .learnings/*.md | wc -l
grep -B5 "Priority**: high" .learnings/*.md | grep "^## ["
grep -l "Area**: backend" .learnings/*.md
Review Actions
- Resolve fixed items
- Promote applicable learnings
- Link related entries
- Escalate recurring issues
Detection Triggers
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
- Log immediately - context is freshest right after the issue
- Be specific - future agents need to understand quickly
- Include reproduction steps - especially for errors
- Link related files - makes fixes easier
- Suggest concrete fixes - not just "investigate"
- Use consistent categories - enables filtering
- Promote aggressively - if in doubt, add to CLAUDE.md or .md
- Review regularly - stale learnings lose value
Gitignore Options
Keep learnings local (per-developer):
.learnings/
Track learnings in repo (team-wide): Don't add to .gitignore - learnings become shared knowledge.
Hybrid (track templates, ignore entries):
.learnings/*.md
!.learnings/.gitkeep
Hook Integration
Enable automatic reminders through agent hooks. This is opt-in - you must explicitly configure hooks. The same two scripts work across Claude Code and Codex CLI (both deliver JSON on stdin and accept the same additionalContext output shape); Copilot hooks can log but not inject context, so Copilot uses the instructions-file channel. Full per-agent setup including Codex and Copilot: references/hooks-setup.md.
Quick Setup (Claude Code)
Create .claude/settings.json in your project. The command path must point to where the skill is actually installed: .claude/skills/self-improvement/ or skills/self-improvement/ if this repo is vendored into the project. Relative paths resolve from the project root.
{
"hooks": {
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/skills/self-improvement/scripts/activator.sh"
}]
}]
}
}
This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead).
Full Setup (With Error Detection)
Hooks receive the event payload as JSON on stdin. The error detector parses tool_response from that JSON and returns its reminder as additionalContext JSON output, which is required for PostToolUse output to reach the model.
Available Hook Scripts
| Script | Hook Type | Purpose |
|---|---|---|
scripts/activator.sh | UserPromptSubmit (Claude Code, Codex) | Reminds to evaluate learnings after tasks (plain stdout is added to context for this event on both agents) |
scripts/error-detector.sh | PostToolUse (Claude Code, Codex), postToolUse (Copilot, logging only) | Parses the stdin JSON payload for error patterns across all three agents' payload shapes; emits an additionalContext reminder |
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
- Identify candidate: Learning meets extraction criteria
- Run helper (or create manually):
./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
- Customize SKILL.md: Fill in template with learning content
- Update learning: Set status to
promotedtoskill, addSkill-Path - Verify: Read skill in fresh session to ensure it's self-contained
Manual Extraction
If you prefer manual creation:
- Create
skills/<skill-name>/SKILL.md - Use template from
assets/SKILL-TEMPLATE.md - Follow Agent Skills spec:
- YAML frontmatter with
nameanddescription - 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 Alsolinks (recurring issue) - High priority + resolved status
- Category:
best_practicewith 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 (UserPromptSubmit, PostToolUse) — experimental, behind codex_hooks = true in config.toml Setup: <repo>/.codex/hooks.json or ~/.codex/hooks.json; same scripts, same payload/output shapes as Claude Code Detection: Automatic via hook scripts; see references/hooks-setup.md for the config Fallback: Add the self-improvement guidance to AGENTS.md if hooks are unavailable
GitHub Copilot
Activation: Instructions file (Copilot hooks exist in .github/hooks/*.json but their output is ignored for prompt/tool events — they can log, not inject context) Setup: Add to .md:
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
Skill平台 (Optional)
Skill平台-specific setup, promotion targets, and hybrid usage details are kept in references/skill-platform-integration.md so this main skill stays focused on the core self-improvement workflow for coding agents.
Agent-Agnostic Guidance
Regardless of agent, apply self-improvement when you:
- Discover something non-obvious - solution wasn't immediate
- Correct yourself - initial approach was wrong
- Learn project conventions - discovered undocumented patterns
- Hit unexpected errors - especially if diagnosis was difficult
- Find better approaches - improved on your original solution
Copilot Chat Integration
For Copilot users, add this to your prompts when relevant:
Or use quick prompts:
- "Log this to learnings"
- "Create a skill from this solution"
- "Check .learnings/ for related issues"
依赖说明
运行环境
- Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- 操作系统: Windows / macOS / Linux
第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
API Key 配置
- 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)
可用性分类
- 分类: MD+EXEC(纯Markdown指令,部分功能需要exec命令行执行能力)
- 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务
核心能力
- Captures learnings, errors, and corrections to enable continuous improvement
- 触发关键词: corrections, self-improving, errors, enable, self, agent, learnings, improving
适用场景
| 场景 | 输入 | 输出 |
|---|---|---|
| 基础使用 | 用户请求 | 处理结果 |
不适用于:需要人工判断的复杂决策场景
使用流程
- 确认运行环境满足依赖说明中的要求
- 根据适用场景选择合适的使用方式
- 执行操作并检查输出结果
- 如遇错误,参考错误处理章节
错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 检查网络连接后重试,参考国内替代方案 |
常见问题
Q1: 如何开始使用Self-Improving Agent?
A: 请先阅读使用流程章节,确认环境满足依赖说明中的要求。
Q2: 遇到错误怎么办?
A: 请参考错误处理章节,按照表格中的处理方式操作。
Q3: Self-Improving Agent有什么限制?
A: 请参考已知限制章节了解具体限制。
已知限制
- 需要LLM支持,无LLM环境无法使用
- 复杂场景可能需要人工辅助判断
- 性能取决于底层模型能力
同分类其他技能
查看全部 ›WorkBuddy签到助手(WorkBuddy「Buddy 加油站」每日签到自动化 Skill,接口直签,跨平台 Windows/mac
50 71.2万 唐朝诗仙李白 · Ai Agent Skill把盛唐诗人李白的诗学观、意象系统与口吻,蒸馏成 AI 可调用的角色包。
5 52.3万 BrowserSkillBrowserSkill 是腾讯开源的一个智能浏览器自动化工具,让 WorkBuddy 能够像人一样操作网页——自动填表、点击、翻页、截
45 52.1万 Agent Browser无头浏览器自动化CLI,为AI Agent优化,支持无障碍树快照与引用提取,精准网页操作
26 52万 Agently MailAgently Mail 是 QQ 邮箱团队为 Agent 打造的专属邮箱服务,与个人邮箱隔离,原生适配 Agent,助力你安全、高效地
85 47.1万 天工.skill天工.skill(Tiangong Skill)智能体设计师。当用户需要设计、创建或优化AI智能体/Agent,或基于真实人物蒸馏思维框
51 44.3万