Ship a self-authored skill

Turn a session where the agent solved something the hard way into a reusable, verified, human-merged skill.

When an agent works out a hard task through trial and error, that trajectory is a skill worth keeping. This guide turns one session into a reusable Skill, authored by the platform, verified by replay, and merged by a human. Nothing reaches a Run unreviewed; the merge is the gate.

Before you start, set the shared variables. CHECKFU_API_KEY is bound to the Workspace. CHECKFU_PRINCIPAL_ID comes from Get access; SESSION is the sess_… you want to capture, SKILL_SOURCE your bound sksrc_… repository, and SERVICE_PRINCIPAL the prin_… the submit acts as.

export CHECKFU_API_KEY="your_api_key"
export CHECKFU_WORKSPACE_ID="wrkspc_0123456789abcdef0123456789abcdef"
export V="Checkfu-Version: 2026-08-24"
export AUTH="Authorization: Bearer $CHECKFU_API_KEY"

The TypeScript tabs below use the TypeScript SDK with this client:

import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({
  apiKey: process.env.CHECKFU_API_KEY,
})

1. Find a skill-worthy session (optional)

   Ask whether a Session’s trajectory looks worth capturing. This is a read-only structural signal, safe under zero-data-retention because it reads only counts:

   cURL

   curl -s "https://api.checkfu.com/v1/skill-proposals/suggestions/$SESSION" \
     --header "$AUTH" --header "$V"
   

   It reports skill_worthy with reasons (many_tool_calls, failure_then_success). It never authors anything; it tells your UI when to offer the button.

2. Author the proposal

   Name 1–8 source Sessions (the first fixes the task class and its Agent) and a model_routing_profile_key. A platform job reads the trajectories and writes one immutable single-file skill.

   cURL

   PROPOSAL_JSON=$(curl -s --request POST "https://api.checkfu.com/v1/skill-proposals" \
     --header "$AUTH" --header "$V" \
     --header "Content-Type: application/json" \
     --data '{
       "source_session_ids": ["'"$SESSION"'"],
       "model_routing_profile_key": "primary",
       "instructions": "Capture the working approach as a reusable skill."
     }')
   PROP=$(jq -r .id <<<"$PROPOSAL_JSON")
   PROPOSAL_VERSION=$(jq -r .version <<<"$PROPOSAL_JSON")
   

   The proposal starts authoring, then reaches drafted (or authoring_failed). Its skill entry is capped at 2560 characters, a verifiability bound explained next.

3. Verify it by replay

   Verification replays the task in one isolated child Session that carries the whole proposed skill in its context, graded by an Outcome rubric derived from the original failure:

   cURL

   curl -s --request POST "https://api.checkfu.com/v1/skill-proposals/$PROP/verify" \
     --header "$AUTH" --header "$V" \
     --header "Content-Type: application/json" \
     --data '{
       "expected_version": '"$PROPOSAL_VERSION"',
       "principal": "'"$CHECKFU_PRINCIPAL_ID"'"
     }'
   

   A pass moves the proposal to verified; a fail to verification_failed (kept, auditable, revisable). Only a verified proposal may submit. The skill rides the graded context rather than a staged mount, which is why its entry is bounded.

4. Submit to the skill repository

   Submit writes the skill to your bound SkillSource repo as a checkfu/<id> branch, through the governed Connection. The branch is the change proposal. expected_version is the verified proposal version you actually reviewed; an exact retry keeps that version, while a stale or changed request conflicts.

   cURL

   # After polling until status is verified, submit the version you reviewed.
   PROPOSAL_VERSION=$(curl -s "https://api.checkfu.com/v1/skill-proposals/$PROP" \
     --header "$AUTH" --header "$V" | jq -r .version)
   curl -s --request POST "https://api.checkfu.com/v1/skill-proposals/$PROP/submit" \
     --header "$AUTH" --header "$V" \
     --header "Content-Type: application/json" \
     --data '{
       "expected_version": '"$PROPOSAL_VERSION"',
       "skill_source": "'"$SKILL_SOURCE"'",
       "acted_as": "'"$SERVICE_PRINCIPAL"'"
     }'
   
5. A human merges; sync delivers

   From here nothing is automatic. A person reviews and merges the branch; you sync the SkillSource; the ordinary path versions the skill and future releases carry it. The proposal records the resulting skill version, closing the chain from session to shipped capability.

Why the gate

The prior art points one way. Hermes stages every self-authored skill behind approval. Voyager admits one only after replay verification, which is where this guide’s verify step comes from. ClawHub left its marketplace ungated and grew a measurable malicious-skill supply chain.

So a verified proposal is a strong, evidence-backed suggestion, and nothing more. A merged skill is a decision a person made. That difference is the product, not a limitation we intend to remove.

Next steps

Capabilities

The SkillProposal lifecycle and the SkillSource loop it adopts through.

Improving instructions from Outcomes

The sibling loop that improves an agent’s instructions instead of its skills.