experience-to-skill

# 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.