Conversation To Skill

Conversation To Skill

This skill turns the work happening in the current conversation into a reusable agent skill.

Its job is not just to write SKILL.md. Its job is to identify the durable workflow, separate it from one-off thread noise, decide the right packaging and placement, and produce a skill that will actually help a future agent perform better.

When useful, this skill should borrow the practical methods of skill-creator: good descriptions, clean skill structure, eval-friendly organization, and an improve-via-feedback loop. When this skill owns evaluation, bundle the relevant toolchain locally under agents/, assets/, eval-viewer/, scripts/, and references/ so it stays self-contained instead of depending on another skill directory at runtime.

Use This Skill For

Use this skill when the user is trying to:

• turn the current task or workflow into a reusable skill
• capture a successful collaboration pattern for future runs
• standardize how a class of tasks should be handled
• extract a repeatable agent workflow from the current thread
• package a reasoning framework, execution sequence, or artifact pattern into a skill
• upgrade an existing draft skill so it is general, usable, and easier to trigger

Typical prompts:

• "Turn what we're doing into a skill."
• "I want this conversation to become an agent capability."
• "Make this reusable for next time."
• "Abstract this workflow into a Codex skill."
• "This should be a standard operating pattern, not a one-off chat."
• "Clean up this skill and make it actually reusable."

Do Not Use This Skill For

Do not use this skill when the user mainly wants:

• a summary of the conversation without creating a reusable skill
• immediate execution of the task with no abstraction step
• a skill generated from multiple unseen threads you cannot inspect
• a rigid template that blindly copies file paths, project names, or temporary constraints
• a generic skill factory that ignores what was actually valuable in the conversation

If the conversation does not yet reveal a stable workflow, say that plainly and help the user clarify the reusable part first.

Core Principles

Capture The Repeatable Value

The skill should capture the repeatable value, not the accidental details.

A good abstraction preserves:

• the job to be done
• the trigger conditions
• the critical inputs and outputs
• the sequence of reasoning or execution
• the judgment criteria that make the workflow valuable
• the boundaries and non-goals

A bad abstraction copies:

• temporary filenames
• irrelevant project-specific paths
• incidental tools that happened to be used once
• order-of-operations that are not actually essential
• user wording that does not generalize

Explain Why, Not Just What

Prefer instructions that explain why a step matters. Avoid brittle mandates unless the workflow truly requires them.

If you find yourself writing a long list of rigid commands with no reasoning, you are probably transcribing the thread instead of building a skill.

Choose The Smallest Useful Shape

Do not overbuild the skill. Use the smallest structure that preserves the capability:

• SKILL.md only, when the workflow is mostly reasoning and sequencing
• SKILL.md plus references/, when the skill needs domain guidance
• SKILL.md plus scripts/, when deterministic repeated work should be bundled
• SKILL.md plus evals/, when the skill benefits from repeatable testing

Decide Placement Before Writing Files

Pick the skill location before creating files so the paths stay stable:

• Global: ~/.agents/skills/<skill-name>
• Project-based: <project-path>/.agents/skills/<skill-name>

If the user wants a global skill to be discoverable by Codex immediately, also create:

• ~/.codex/skills/<skill-name> as a symlink to the global skill directory

If you plan to run evals, place the workspace next to the skill directory as:

• <skill-name>-workspace/

Default Workflow

Follow this sequence unless the user already provided enough structure.

1. Extract The Candidate Skill From The Current Thread

Read the current conversation first. Pull out the real workflow before asking the user to restate everything.

Capture:

• what the user was trying to achieve
• what sequence of steps the agent followed or should follow
• which tools or artifacts mattered
• what corrections or preferences the user introduced
• what output the user actually wanted
• what makes this reusable instead of one-off

2. Separate Stable Pattern From Incidental Context

Classify each detail into one of three buckets:

• Core: must stay because the skill breaks without it
• Contextual: useful examples or defaults, but not universal
• Incidental: this-thread noise that should not be baked into the skill

Useful heuristic:

• if the detail would still matter in six months on a different project, it is probably core
• if it only mattered because of this repository, filename, or user phrasing, it is probably contextual or incidental

3. Fill Gaps With Minimal Interview Or Research

Do not ask the user to restate the whole workflow if the thread already tells you most of it. Only ask for the missing pieces that affect the resulting skill:

• what this skill should enable the agent to do
• when the skill should trigger
• what output format or artifact the user expects
• whether lightweight test prompts would help validate the result

If examples, edge cases, dependencies, or adjacent skills matter, gather that context before writing the final version.

4. Produce An Abstraction Brief Before Writing Files

Before generating the final skill, write a short abstraction brief for the user to review unless they already said to just build it.

Use this structure:

## Skill Intent
- Name:
- Goal:
- Why this should exist:

## Trigger
- Use when:
- Do not use when:

## Inputs
- Required inputs:
- Optional inputs:

## Outputs
- Main deliverable:
- Secondary artifacts:

## Workflow
1. ...
2. ...
3. ...

## Judgment Rules
- What must stay true:
- What to avoid:

## Open Questions
- ...

If the conversation already settles these points, keep the brief short and move on.

5. Challenge Weak Abstractions

Do not act like a passive stenographer. If the proposed skill is overfit, under-scoped, or missing the real judgment logic, say so and correct it.

Common failure modes to call out:

• "This is a transcript, not a skill."
• "These instructions depend on this exact repo, but the user asked for a global skill."
• "The workflow says what to do, but not how to decide when a step is necessary."
• "The description would under-trigger because it only names one phrasing."
• "This skill repeats manual work that should be moved into a bundled script."

6. Decide Location, Shape, And Scope

Make these decisions before writing:

• whether the skill is global or project-based
• whether to preserve an existing name and directory
• whether SKILL.md alone is enough
• whether the skill needs references/, scripts/, assets/, or evals/
• whether a sibling workspace should be created for testing

Default location rules:

• Global skill: ~/.agents/skills/<skill-name>
• Project-based skill: <project-path>/.agents/skills/<skill-name>

If updating an existing skill, preserve the directory name and frontmatter name unless the user asked for a rename.

7. Write The Skill Like A Real Skill

When writing SKILL.md, include:

• frontmatter with name and a trigger-oriented description
• what the skill is for
• when to use it and when not to use it
• the default workflow
• output expectations
• edge cases and boundaries when they materially affect quality

Bring in the skill-creator quality bar here:

• make the description a little aggressive so hosts do not under-trigger it
• include both what the skill does and the contexts that should trigger it
• prefer imperative instructions
• explain the reasoning behind important steps
• keep the file readable; if it grows too large, move detail into references