self-improving-agent

概述

For CI-only execution, use:

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

Quick Reference

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
• promoted_to_skill – 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

工作空间 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 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: <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
• 工作空间 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

Area Tags

Use to filter learnings by codebase region:

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

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:

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 promoted_to_skill, 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

第三方依赖

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环境无法使用
• 复杂场景可能需要人工辅助判断
• 性能取决于底层模型能力