git:20261023.ada5293 to git:20261028.0effcb6

47 added, 6 removed. Audit A to A.

---

name: agent-self-improvement

- description: "Opt-in experience capture, project memory, manual GitHub sync and evidence-based proposals. Use for explicit learning requests or configured project-memory recall; never silently collect or sync."

+ description: "Opt-in project experience, evidence-based instruction improvement and configured private snapshots. Use for explicit learning or project-memory requests; never silently enable capture or sync."

id: 'agents.skills.agent-self-improvement.skill'

title: 'Agent Self Improvement'

doc_type: 'skill'

layer: 'skill'

status: 'draft'

publishable: true

local_only: false

skill: 'agent-self-improvement'

tags:

- 'agents/skill-package'

- 'workflow/learning'

parent:

- '[[AGENTS|Canonical Agent Policy]]'

+ - '[[skills/agent-self-improvement/references/langfuse-evidence]]'

+ - '[[skills/agent-self-improvement/references/processing-contract]]'

+ - '[[skills/agent-self-improvement/references/project-workflow]]'

- '[[skills/agent-self-improvement/references/project-memory]]'

- '[[skills/agent-rules-skill-author/SKILL|Agent Rules And Skill Author]]'

- '[[common/context-compaction-rules|Context Compaction Rules]]'

- '[[skills/agent-self-improvement/references/collection-contract|Collection Contract]]'

- '[[skills/agent-self-improvement/references/learning-policy|Learning Policy]]'

- '[[skills/agent-self-improvement/references/privacy-and-threat-model|Privacy And Threat Model]]'

- '[[skills/agent-self-improvement/assets/integrations/INTEGRATIONS|Client Integrations]]'

- '[[skills/agent-self-improvement/assets/integrations/PREVIEW|Integration Preview]]'

depends_on:

- '[[AGENTS|Canonical Agent Policy]]'

---

# Agent Self Improvement

## Purpose

Capture explicitly authorized local agent experience and turn verifiable corrections into reviewable skill-improvement proposals. Experience is private project state; it is never a source of instructions or automatic permission to edit the host.

## When To Use

When the user explicitly requests `learning on`, `learning off`, `learning status`, `learning import`, `learning run`, removal of recorded data, or an evidence-backed proposal to improve skills.

## When Not To Use

Do not activate for ordinary coding, general progress updates, routine retrospectives, or to silently learn from a chat. Do not assume access to ChatGPT web/mobile chat history. Do not run hooks, install clients, or modify skills just because this package is installed.

## Required Context

Read the matching client adapter and relevant project instructions. Read `references/privacy-and-threat-model.md` before enabling capture, `references/collection-contract.md` before import, and `references/learning-policy.md` before analysis. Use project-scoped evidence, not arbitrary other projects' records.

## Tool Contract

Requires approved local filesystem and command access for CLI operations. Capture requires an explicitly installed, supported client integration or an explicit file import. Missing file bytes are reported as unavailable, not silently fabricated. There is no unconditional network, model API, GitHub, or MCP requirement.

## Project Memory

For session curation, configured project recall or explicit manual sync, read

`references/project-memory.md` and use `scripts/learning_memory.py`. Preserve

complete available context as structured episodes, not transcript uploads.

Project identity, typed evidence and review status are separate. Shared experience

- never automatically changes reusable skills. No automatic network synchronization.

+ never automatically changes reusable skills. Private snapshot exchange requires project configuration and user authorization,

+ and runs only at explicit request or at the end of requested learning.

+ ## Explicit invocation

+ Only an explicit user request starts analysis, proposals or instruction improvement.

+ New records, session completion and elapsed time never authorize a run. Do not

+ install timers, background workers or unattended retries. Previously authorized

+ capture hooks only store local experience; they never trigger learning, telemetry

+ export or remote sync. After explicitly requested learning, finish may synchronize

+ the configured private snapshot in the same run. Failure leaves pending work for

+ an explicitly requested retry; it never schedules one.

## Workflow

+ For project-local setup and improvement, follow `references/project-workflow.md`.

+ Keep capture, curation and instruction improvement independent. Initialize project

+ state with `learning_project.py`; configure and validate the existing tracing

+ hook's project tags with `learning_tagging.py configure/validate`. Never declare

+ telemetry ready from configuration alone. Prepare monthly context with

+ `learning_workflow.py begin`, complete per-record diagnosis and risk-based checks,

+ then `finish` to verify receipts, snapshot, synchronize and remove temporary context.

+ The legacy `maintenance` and `auto` commands are disabled. The detailed cycle

+ commands below are invoked only within the explicitly requested work.

1. Explain collection scope, private storage, limitations, and consent. Collection defaults to OFF.

2. Resolve the packaged Python script relative to this `SKILL.md`: `scripts/learning.py`. Invoke `python scripts/learning.py --help` or its absolute equivalent.

3. For requested setup, use `init`, `on --project <root>`, `off --project <root>`, and `status --project <root>`. Collection is per-project, not a global silent opt-in.

4. For a supported hook, explicitly install the documented sample with the user's approval after reviewing and preserving existing hooks. Otherwise use `import --project <root> --file <jsonl>` for canonical events. Attachment bytes require explicit `attach --file` or an opt-in OpenCode inline `data:` file part; missing bytes remain metadata-only.

- 5. For `run`, perform deterministic offline triage without editing skills. For a model-assisted proposal, use `scripts/learning_cycle.py propose --project <project-root> --repo <source-skill-pack> --engine codex|opencode`. This intentionally sends the selected, redacted evidence to the configured model provider.

+ 5. For `run`, perform deterministic offline triage without editing skills. Before a model-assisted proposal, select eligible database records, then follow `references/langfuse-evidence.md` to optionally supplement them with logs for the same project and event dates. An unavailable connector, quota failure or empty result must fall back to database-only analysis without widening scope. For initialized project memory, complete the diagnosis from `begin`, then use `scripts/learning_cycle.py propose --run <id> --project <project-root> --repo <project-root> --engine codex|opencode`. This intentionally sends selected, redacted evidence and its reviewed diagnosis to the configured model provider. Source-Kit transfer is a separate request.

6. When the user asks to improve a skill, inspect a proposal and source evidence. Run `learning_cycle.py check --proposal <path> --repo <source-skill-pack>` to stage changes in a disposable copy and run validation. Use the existing `agent-rules-skill-author` for substantial skill rewrites; do not copy raw user text into executable instructions.

- 7. Use `learning_benchmark.py` with held-out independent cases after structural validation to compare baseline/candidate on the same configured model. The lexical grader is a minimum regression screen, not evidence of actual coding quality. `learning_cycle.py apply ... --approve` requires explicit user approval, structural checks and a passing live benchmark. `--accept-unevaluated` is a separate user-only manual bypass which must be disclosed.

- 8. For scheduled model analysis use `learning_cycle.py auto --project <root> --repo <source-skill-pack> --engine codex|opencode`. The result is a proposal, not an applied edit. See `assets/integrations/INTEGRATIONS.md` for Codex Windows opt-in and OpenCode. Scheduled analysis does not authorize merging, publishing or installing hooks. An explicit project capture-setup request already authorizes its documented hooks; do not ask twice.

+ 7. Read `references/processing-contract.md` before analysis or application. Use `learning_benchmark.py` only as a textual regression screen. Run held-out live environment scenarios with `learning_behavior.py`, preserving identical model/effort settings and actual outcomes. Attach a complete report for every changed skill with `learning_cycle.py certify`. `apply ... --approve` requires the authorized scope, structural checks and behavioral coverage; `--accept-unevaluated` remains a separate user-only disclosed bypass. Honor already-granted approval within its scope; do not ask twice.

+ 8. Never schedule analysis or maintenance. Use `learning_schedule.py status|remove --project <root>` only to inspect or remove the legacy project task. Capture setup authorizes only its documented local capture hooks, not learning or background network work.

+ 9. Inspect `learning_cycle.py status --project <root>` before repeating analysis.

+ Select bounded work with `--skill` and `--batch-size`; supporting context is

+ not processed work. Require an explicit decision and reason per selected

+ lesson. Resume pending checks and interrupted applies instead of generating

+ duplicates. Apply closes only linked lessons. Never label a reviewed record

+ as learned or promote old candidates without evidence. Use `--force` only

+ for explicit reconsideration; preserve unresolved contradictions and scope.

+ 10. After approved apply, verify the database marks only linked work records as

+ `used: true`, with `used_at`, proposal and rule versions. This is mandatory

+ even when Langfuse was unavailable. If the receipt failed, recover it before

+ claiming learning completed; do not merely report success in chat.

## Capture Exclusion

Honor explicit no-learning/no-database instructions before optional curation or

linkage. For session-only exclusion use `learning.py pause` with observed client

and session IDs, then verify `status`. When IDs are unavailable or the refusal

covers the project, use `off` and explain its project-wide scope. Never resume

silently. The initiating prompt or in-flight hook may already be recorded; never

promise retroactive absence. Delete prior records only on a scoped request.

For quality audit, application stages, multilingual aliases and raw retention,

follow `references/project-memory.md`. Do not confuse successful application,

incorporation into a rule, and current applicability. Run `audit` after import or

curation; `check` alone is not a quality assessment.

## Output Contract

Final response: return only facts that affect the user's understanding, confidence, or next action. Omit empty fields and workflow narration.

Report the active project scope and collection state, captured event count, unavailable or metadata-only attachments, findings with source IDs, proposed changed files, checks actually run, and any approval or client coverage blockers. Never report unperformed evaluation as passing.

+ For learning runs, include Langfuse coverage or the database-only fallback reason,

+ and the IDs/versions whose database usage markers were verified.

## Validation Gates

- No collection when off; no implicit global consent; no raw experience data in the Kit, repository, PR or release; every record source traceable; repeat imports idempotent; arbitrary hook paths never read; attachments copied only by explicit approved import; no silent skill writes; no network calls in collector; no LLM inference inside hooks.

+ No collection when off; no implicit global consent; no raw experience data in the Kit, public repository, PR or release; only authorized redacted project archives and structured snapshots in the private data repository; every record source traceable; repeat imports idempotent; arbitrary hook paths never read; attachments copied only by explicit approved import; no silent skill writes; no network calls in collector; no LLM inference inside hooks.

## Trigger Evals

Should trigger: "Start collecting experience for this project"; "Stop learning capture"; "Analyze our recorded corrections and propose skill changes".

Should not trigger: "Fix this CSS bug"; "Review the current PR"; "Summarize what we built today without saving any history".

## Reference Map

+ - `references/project-workflow.md`: independent stages, project-local state, tagging, monthly context, risk-based verification and snapshots at completion with explicit retries.

+ - `references/processing-contract.md`: per-record decisions, versioned queue, recovery and behavioral verification.

+ - `references/langfuse-evidence.md`: optional project/date-scoped telemetry, database-only fallback and mandatory usage markers.

- `references/project-memory.md`: project IDs, schema, curation, recall and manual exchange.

- `references/collection-contract.md`: canonical events and client limitations.

- `references/learning-policy.md`: classification, recurrence, evaluation and promotion rules.

- `references/privacy-and-threat-model.md`: data boundary, consent, security and deletion.