experience-to-skill

name	experience-to-skill
description	Use when deciding whether a reusable lesson or repeated workflow should become a skill, memory, AGENTS rule, script, project doc, or stay unrecorded.

Experience To Skill

Overview

Turn useful experience into the right durable artifact. Not every lesson should become a skill: choose the smallest place that will make future work better without bloating global context.

When to Use

Use this skill:

• At the end of a complex or repeated task.
• When the same workflow has appeared about three times.
• When a non-obvious debugging path, verification gate, or tool sequence saved time.
• When the user asks to "make this reusable", "turn this into a skill", "update memory", "sync up", or similar.
• When a future agent would likely repeat the same mistake without written guidance.

Do not use it for one-off facts, project secrets, raw transcripts, or normal code comments.

Artifact Decision

Choose one primary destination:

Destination	Use when	Avoid when
Skill	Reusable cross-project workflow or judgment pattern	It is only true for one repo
Project AGENTS.md	Project-specific agent rule, route, command, or boundary	It should apply globally
Global AGENTS.md	Stable cross-project user preference or machine rule	It is domain/project-specific
Memory	Lightweight preference or historical fact useful across sessions	It needs executable steps
Script	Deterministic repeated operation	Human judgment is central
Docs/README	Humans or downstream systems need to use the knowledge	Only agents need it

Workflow

1. Extract the reusable lesson.

   • State the trigger: when should a future agent remember this?
   • State the action: what should it do differently?
   • State the evidence: why is this worth preserving?

2. Check for an existing artifact.

   • Search current skills and project docs first.
   • Prefer updating an existing skill or rule over adding a near-duplicate.

3. Pick the narrowest durable home.

   • Global skills stay small and general.
   • Project-specific behavior belongs in the project.
   • Repeated mechanical operations should become scripts, not prose.

4. Write or update the artifact.

   • For skills, use skill-creator or writing-skills.
   • Keep frontmatter trigger-focused.
   • Keep body concise and procedural.
   • Do not include secrets, private tokens, or raw sensitive logs.

5. Validate.

   • Confirm paths exist.
   • Confirm the trigger description would cause the skill to load at the right moment.
   • Confirm the new artifact does not conflict with existing rules.

Skill Creation Criteria

Create or update a skill only when most of these are true:

• The pattern is reusable across projects.
• The task involves judgment or a workflow, not just a fact.
• The behavior is not already covered by an installed skill.
• The trigger can be described clearly in frontmatter.
• The skill will prevent a real future mistake or reduce repeated setup work.

Common Mistakes

• Turning every lesson into a global skill.
• Appending new rules without deleting or merging stale ones.
• Storing project-specific domain rules globally.
• Writing a narrative of what happened instead of a reusable procedure.
• Treating generated files or green tests as proof that knowledge is correct.