Agent Skill

self-improving-agent

自我改进Agent快速参考,按情境对照行动

AI Agent·智创未来·来自 skill_hub·skillhub.cn ↗
skillhub install @zcwl/self-improving-agent
5 Stars·28.7万 综合热度·11,850 字文档·源站更新 2026-11-22

README 文档

11,850 字

For CI-only execution, use:

安装此Skill请参考SkillHub平台指南

Quick Reference

SituationAction
Active failure mid-task — agent needs to fix it nowUse 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 youLog to .learnings/LEARNINGS.md with category correction
User wants missing featureLog to .learnings/FEATURE_REQUESTS.md
API/external tool failsLog 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 outdatedLog to .learnings/LEARNINGS.md with category knowledge_gap
Found better approachLog to .learnings/LEARNINGS.md with category best_practice
Simplify/Harden recurring patternsLog/update .learnings/LEARNINGS.md with Source: simplify-and-harden and a stable Pattern-Key
Similar to existing entryLink with See Also, consider priority bump
Broadly applicable learningPromote 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:

  1. Change Status: pending → Status: resolved
  2. 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 on
  • wont_fix - Decided not to address (add reason in Resolution notes)
  • promoted - Elevated to CLAUDE.md, AGENTS.md, or .md
  • promotedtoskill - 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

TargetWhat Belongs There
CLAUDE.mdProject facts, conventions, gotchas for all Claude interactions
AGENTS.mdAgent-specific workflows, tool usage patterns, automation rules
.mdProject context and conventions for GitHub Copilot

工作空间 targets (SOUL.md, TOOLS.md) are covered in references/skill-platform-integration.md.

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 .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:

  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 .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 simplifyandharden.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: <pattern_key>" .learnings/LEARNINGS.md
  1. If found:
  • Increment Recurrence-Count
  • Update Last-Seen
  • Add See Also links to related entries/tasks
  1. 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
  • 工作空间 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

PriorityWhen to Use
criticalBlocks core functionality, data loss risk, security issue
highSignificant impact, affects common workflows, recurring issue
mediumModerate impact, workaround exists
lowMinor inconvenience, edge case, nice-to-have

Area Tags

Use to filter learnings by codebase region:

AreaScope
frontendUI, components, client-side code
backendAPI, services, server-side code
infraCI/CD, deployment, Docker, cloud
testsTest files, testing utilities, coverage
docsDocumentation, comments, READMEs
configConfiguration 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 .md
  8. 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

ScriptHook TypePurpose
scripts/activator.shUserPromptSubmit (Claude Code, Codex)Reminds to evaluate learnings after tasks (plain stdout is added to context for this event on both agents)
scripts/error-detector.shPostToolUse (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:

CriterionDescription
RecurringHas See Also links to 2+ similar issues
VerifiedStatus is resolved with working fix
Non-obviousRequired actual debugging/investigation to discover
Broadly applicableNot project-specific; useful across codebases
User-flaggedUser says "save this as a skill" or similar

Extraction Workflow

  1. Identify candidate: Learning meets extraction criteria
  2. Run helper (or create manually):
   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
  1. Customize SKILL.md: Fill in template with learning content
  2. Update learning: Set status to promotedtoskill, add Skill-Path
  3. 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:
  • 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 (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:

  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:

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 APIAPI必需由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

适用场景

场景输入输出
基础使用用户请求处理结果

不适用于:需要人工判断的复杂决策场景

使用流程

  1. 确认运行环境满足依赖说明中的要求
  2. 根据适用场景选择合适的使用方式
  3. 执行操作并检查输出结果
  4. 如遇错误,参考错误处理章节

错误处理

错误场景原因处理方式
配置错误参数缺失或格式错误检查依赖说明中的配置要求
运行时错误运行环境不满足确认运行环境符合依赖说明
网络错误连接超时或不可达检查网络连接后重试,参考国内替代方案

常见问题

Q1: 如何开始使用Self-Improving Agent?

A: 请先阅读使用流程章节,确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办?

A: 请参考错误处理章节,按照表格中的处理方式操作。

Q3: Self-Improving Agent有什么限制?

A: 请参考已知限制章节了解具体限制。

已知限制

  • 需要LLM支持,无LLM环境无法使用
  • 复杂场景可能需要人工辅助判断
  • 性能取决于底层模型能力

同分类其他技能

查看全部 ›