Learned skills

Learned skills store reusable instructions in the agent's durable database. Unlike filesystem skills, they are managed through tools, retain revision history, and can apply to one checkout, a repository, or all your projects. They are for procedures and constraints—not a replacement for conversation history or a place to store credentials.

Choose a scope

Use the narrowest scope that remains useful. When instructions conflict, checkout guidance overrides repository guidance, which overrides user guidance. Repository scope does not mean a file is committed to Git; use SKILL.md or AGENTS.md when you need instructions distributed with source control.

Activation modes

Priority controls ordering and defaults to 0; accepted values are integers from -100 to 100. Higher priority is not permission to override the user's current request or the repository's instructions.

Capture a verified procedure

1. Complete and verify the actual task first. Record the command, conditions, and result.
2. Ask the agent to search existing learned skills before proposing a new one.
3. Review the proposed scope, applicability, and exact instructions.
4. Approve the creation only when the lesson is reusable and supported by evidence.
5. Ask the agent to read it back with its scope and revision number.

Search existing learned skills for this repository's integration-test procedure. If none covers the verified procedure from this session, propose a repository-scoped relevant skill. Include the exact command and its prerequisites, and show me the instructions before saving.

This is a request to the agent, not a slash command. The model uses the learned-skill tools below. The expected result is a stored skill with a revision, not merely a promise that the model will remember. Mutations require approval under the active tool policy.

Management tools

A create request has this shape. This is a tool payload for reference—not a JSON file to place in your repository. Replace the illustrative evidence with an actual verified result.

{
  "scope": "repository",
  "slug": "integration-test-procedure",
  "title": "Run integration tests in the project environment",
  "description": "Use the verified project environment for integration tests.",
  "applies_when": "Changing code covered by the integration suite.",
  "instructions": "Enter the project Nix shell and run the verified integration-test command. Report failures before proceeding.",
  "activation": "relevant",
  "priority": 0,
  "change_summary": "Record the verified test procedure.",
  "evidence": "Replace with the actual command and observed result."
}

Revise and restore

Read the current revision before updating. The expected_revision check prevents one session from silently overwriting a newer edit from another. If the revision changed, reread the skill and reconcile the changes rather than blindly retrying.

Archiving keeps the immutable history but excludes the skill from active search and future loading. Rollback creates a new revision containing the selected earlier contents and status; it does not erase intervening history. To restore an archived skill, select an earlier active revision.

Read repository skill integration-test-procedure and show its revision history. Compare the current instructions with revision 1. Do not change it until I confirm which procedure is correct.

Automatic post-task review

The bundled post-task-learning-review guidance applies before the top-level agent finishes substantial work. It considers surprising failure causes, repository conventions, reliable checks and recurring preferences. It first searches existing learned skills and prefers updating one over creating a duplicate.

The procedure allows at most two learned-skill mutations per task and requires a reusable, non-obvious, evidence-backed lesson likely to change future behavior. Ordinary task summaries, temporary state, speculation and already-documented repository instructions do not qualify. If nothing meaningful was learned, the expected outcome is no mutation and no review announcement. This guidance does not bypass approval.

Verify and troubleshoot

• Not found: confirm the scope and current repository/checkout. Search excludes archived skills; use the known name and scope to inspect history.
• Not automatically applied: inspect activation and applicability. A manual skill is intentionally not selected just because a task seems related.
• Duplicate guidance: update or archive an existing skill instead of creating another copy. Inspect narrower scopes for an override.
• Old instructions remain in this conversation: archiving affects future retrieval, not text already included in conversation history. Explicitly correct the current session and verify behavior in a new session.

Never store tokens, passwords, private message contents, or one-off task status as a learned procedure. Review evidence and instructions before approving a durable mutation.