# Improving skills with agent feedback

The platform can use feedback reported by agents and sampled efficacy scores to propose changes to a skill. The review workflow keeps those proposals separate from the current `SKILL.md` until a project member approves them.

## What agents report

After using a skill, an agent can report whether it helped, partially helped, did not help, was misleading, or was harmful. A report can include a short note and the skill version used in the session. Plugins that carry skills bundle a local feedback server for exactly this purpose, and assistants report through a built-in feedback tool.

These reports are raw, agent-reported signals. They are inputs to analysis, not authoritative measurements of a skill's efficacy. Treat outcome counts and notes as context alongside sampled [efficacy scores](/docs/ai-control-plane/distribute/skills/measuring-skill-efficacy), session rationale, and version trends.

## How analysis works

An automated analysis agent reviews eligible feedback and scored sessions for a skill. When the evidence supports a concrete improvement, it records the edit as a diff against the skill version it analyzed, along with a short summary of what goes wrong today and what the edit fixes, a link to every feedback record the proposal was generated from, how many scored sessions informed the proposal, and the exact skill version used as the proposal's base.

The analysis agent does not update the skill directly. The proposal remains an open suggestion until someone reviews it.

A suggestion is a list of separate changes rather than one rewritten manifest. Each change is self-contained and cites only the feedback behind it, so a reviewer reading a change sees the reports that motivated it and not the ones behind an unrelated edit. On each analysis pass, open changes are replayed onto the current version: the ones that still apply are carried forward, and the ones that conflict or are already applied are dropped. A suggestion is superseded once nothing is left to propose.

## Review a suggested edit

The skill detail page shows a suggested edit as a diff between the current and proposed manifests, with a review marker beside each proposed change. Expanding a marker shows that change's summary, how many sessions asked for it, and the agent reports cited as its reason.

Project members with skill write access can act on a suggestion in two ways.

- **Apply** takes just one change. A new immutable version is recorded carrying only it, and the suggestion stays open proposing the remaining changes, now measured against the version just created. Applying the last remaining change closes the suggestion.
- **Apply all** reviews every change the suggestion still proposes and takes them as one new version. The complete proposed manifest can also be adjusted before applying it, or the suggestion dismissed without changing the skill. The normal manifest validation and 65,536-byte limit still apply.

There is no draft state. Every apply records a new version immediately, and that version becomes the one agents load, so plugin distributions that are not pinned to a specific version pick it up.

Approval applies the change to the version that is current at that moment. If the change no longer applies, the platform reports a conflict or supersedes the suggestion rather than applying it over newer work.

The skills list can also approve suggestions in bulk with **Approve all**. The confirmation dialog shows the exact set that will be processed; suggestions created after the dialog opens are not included. Each suggestion is processed independently, and the result reports applied, superseded, conflicting, and failed outcomes. Review the reported counts instead of assuming every suggestion was applied, and if the request fails, refresh and review the current state before retrying because some edits may already have been applied.

## Read feedback and regression signals

The collapsed **All agent reviews** section at the bottom of a skill shows all-time outcome counts and recent notes across every report, not only the ones behind the current suggestion. It also tracks collection health: how many reports are unreviewed, what share of activations produced feedback, and how many reports were cited in suggestions. **Generate suggestion** runs the analysis on demand using unresolved reviews and efficacy evidence.

Skill insights may also show a regression warning when the current version scores worse than its predecessor. The warning includes current and predecessor scores and sample counts and links to the predecessor in version history.

## Restore an earlier version

Version history can restore any valid, non-current version. Restoring makes that historical content current again without changing the immutable historical record. Versions are content-addressed, so a restore reactivates the existing version rather than creating a duplicate with the same canonical content. It does not rewrite or remove versions.

Explicit distribution pins for plugins and assistants are preserved. A pinned distribution continues to target its selected version; only distributions that follow the current skill version observe the restore.