Skill proposals

3 min readReferenceUpdated 2026-05-19

What you'll find here

SkillChangeProposal — how agents draft changes to reusable operating guidance without silently changing their own authority.

Proposals are not updates.

Reviewable records that can be cited by later approval gates, eval / replay checks, rollback plans, and learning-loop receipts.

Fields

Proposal id

Skill package id

Task id

Title · summary · rationale · proposed change

Source

telemetry · operator · review.

Status

pending_review · approved · rejected.

Policy envelope id

Evidence ids

Telemetry ids

Receipt ids

Optional improvement plan

Creator & creation timestamp

Agent-created proposals stay pending_review.

Review and promotion are separate gates. Telemetry-sourced proposals require telemetry ids so reviewers can inspect the observed behavior that motivated the change.

Improvement plans

SkillImprovementPlan adds structured review details:

Field

Values

Notes

Expected benefit

prose

What improvement to expect.

Risk

low / medium / high / critical

High & critical require replay fixture ids.

Rollback notes

prose

The path back.

Proposed edit targets

list

Where the change applies.

Replay fixture ids

list

Required for high / critical risk.

Approved proposals require an improvement plan.

Reviewers must inspect benefit, risk, edit scope, and rollback path before promotion.

What's next

ReferenceSkill promotion gatesTurn an approved proposal into promoted guidance.ReferenceSkill replayCompare current behavior against fixtures before promotion.ReferenceSkill rollbacksThe reviewable path back to a prior promoted version.