Skill drafting and verification

@pi-kit/learn creates a proposed skill from a thread's messages, tool calls, checks, and outcome. The draft is stored in pi-kit's database. Approval installs it as an ordinary pi skill in the selected project or user directory. This changes the instructions available to subsequent tasks; it does not train or fine-tune the model.

For a runnable exercise, use the self-learning example.

Use /learn, the thread menu, or the outcome menu. Manual drafting is available for threads with messages. Verification additionally requires a recorded outcome and its base/head commits.

With the attendant enabled, qualifying completed threads can produce drafts automatically under its cost cap. Eligibility considers the amount of work and existing skills to avoid redundant drafts.

With the attendant disabled, a manual request can ask for consent before sending the reduced transcript to the configured model. Redaction runs before analysis; the model may be local or hosted.

If the command is missing, check that the bundled learning package is installed and loaded. Its host workflow requires pi-kit event handlers; it is not a standalone CLI analysis command.

Analysis uses a reduced, redacted transcript: prompts, tool calls and their targets/results, errors and subsequent recovery, recognized checks, and the outcome diff/commit message when available. The analysis model converts these into a name, a description of when the skill applies, and procedural instructions in SKILL.md format.

For example, a thread fixing input normalization can yield a procedure for reading existing behavior, adding edge-case tests, changing the implementation, and running the relevant test command. The intended reusable part is the procedure, not the original file contents. The analysis model can produce incomplete or overly specific instructions, so the draft is editable.

Choose Read on the draft card to open its learning workspace. It contains the skill name, description, editable instructions, scope, and verification controls. The workspace can be left and reopened from the sidebar; the draft remains associated with its source thread.

A reusable skill should describe the procedure, relevant constraints, and checks. Replace details that apply only to the original task when they are not needed in later uses. The review controls validate the skill format and name before installation.

Verification creates a scratch worktree at the outcome's base commit, pins the draft skill, and starts a new thread with the original first prompt. The prompt can be edited before starting.

The report compares the replay with the outcome:

Verification uses a model run and may incur provider costs. Only one replay runs at a time. The normal Stop control interrupts it. Missing commits, unavailable models, setup failures, or untrusted resources can prevent a replay.

The replay uses a separate working directory but is not a tool sandbox. Commands, absolute paths, or project scripts can affect other directories. pi-kit compares the main checkout before and after the run and reports changes, without attributing every change to the replay.

Verification does not merge or push its result. A successful replay describes reproduction of one recorded outcome, not general correctness of the skill.

Approve writes the validated skill to the chosen project/user skills directory. An existing skill with the same name is not overwritten; choose another name. Resource reload makes the approved skill available in the composer.

Discard leaves the draft record but installs no skill. A discarded draft can be reopened from the thread menu and is not repeatedly drafted automatically from the same source.

During verification, a temporary copy of the skill is written inside the scratch checkout. That is separate from installing the approved skill.

Open Settings → Skills → Library to inspect provenance, uses, outcomes, and verification records. Available actions include editing, re-verifying, and retiring a skill. Package installation/enabling is under Extensions → Packages.

Recheck instructions when project conventions or test commands change. Learned skills use the standard SKILL.md format and can be edited or distributed like other pi skills.