Reflect

Analyze the current session and turn what was learned into concrete edits to the skill's source file.

Workflow

1. Identify the Skill

Auto-detect which skills were used by scanning the conversation for:

• <command-name>/skill-name</command-name> tags
• Reads of a skill's source file (a SKILL.md or <skill-name>.md in a skills directory)

If a skill name was provided as an argument, use that directly.

If multiple skills were detected, ask which to analyze. If none were detected and no argument was given, list the available skills and ask.

If a skill was generated by dot-ai, its source: frontmatter records the repository it came from. Use that to find the skill's source file in the matching local checkout before proposing or applying edits (different skills may live in different repositories).

2. Analyze the Conversation

Scan the conversation for these signals:

Do not capture as skill changes: one-off or context-specific instructions ("just this time", "only in this repo"), questions, vague praise with no identifiable cause, or anything that would not generalize to future runs. Reflect durable, generalizable signals only.

3. Propose Changes

A change can target the skill body (its behavior and instructions) or its description / trigger phrases (when the signal is a trigger misfire). Pick whichever the evidence points to.

If no actionable signals are found, report that the skill performed well and end:

No improvements identified for [skill-name]. The skill performed well in this session.

Otherwise, present findings:

+-- Skill Reflection: [skill-name] ----------------------------+
|                                                               |
|  Signals: X corrections, Y successes, Z edge cases           |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Section: "specific change description"              |
|  [MED]  + Section: "specific change description"              |
|  [LOW]  ~ Note: "observation for review"                      |
|                                                               |
|  Commit: "[skill]: [summary of changes]"                      |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

4. Apply (if approved)

1. Locate the skill's source file in its skills repository and read it.
2. Apply the changes with the Edit tool.
3. Commit and push the change to that repository.
4. Confirm: "Skill updated and pushed."

If declined, acknowledge and end.

5. Consolidate (when the skill is getting bloated)

Reflection should not only add. When the skill's body has grown long or accumulated overlapping guidance (rule of thumb: it exceeds ~100 lines, or you notice redundant or contradictory entries), do a consolidation pass:

• Merge duplicate or near-duplicate entries into one.
• Remove guidance that is outdated or superseded by a newer entry.
• Regroup related points under the right section.

Present it through the same propose/approve flow (Steps 3-4). A net reduction in length is a good outcome.

Example

User runs /reflect after a frontend-design session where they corrected gradient usage and dark background colors:

+-- Skill Reflection: frontend-design -------------------------+
|                                                               |
|  Signals: 2 corrections, 3 successes                         |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Constraints: "Never use gradients unless            |
|           explicitly requested"                               |
|  [HIGH] + Color & Theme: "Dark backgrounds: use #000,         |
|           not #1a1a1a"                                        |
|  [MED]  + Layout: "Prefer CSS Grid for card layouts"          |
|                                                               |
|  Commit: "frontend-design: no gradients, #000 dark bg"        |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

Constraints

• Always show the exact proposed changes before applying.
• Never modify skills without explicit user approval.
• Push only after a successful commit.
• Edit the source file in its repository, never the generated copy in your agent's skills directory (it is overwritten on the next regeneration).
• Prefer editing or merging an existing entry over appending a new one; keep the skill tight.