reflecting-on-skills

Reflecting on Skills

This skill is automatically triggered after any other skill completes (via a PostToolUse hook).

Platform Compatibility

Claude Code Only: This skill uses PostToolUse hooks and the Task tool for background subagent execution. These features are specific to Claude Code and not available in Claude apps or via the API.

For the cross-platform Agent Skills specification, see agentskills.io.

Instructions

When invoked after another skill completes:

1. Identify the skill - Determine which skill was just used from conversation context

2. Launch background analysis - Use the Task tool:

   Task tool with:
     subagent_type: "general-purpose"
     run_in_background: true
     prompt: [see below]
   

3. Subagent prompt template:

   Analyze the skill that was just used in this conversation.
   
   1. Read the skill's SKILL.md file at: ~/.claude/skills/[skill-name]/SKILL.md
   2. Review the conversation to identify:
      - Errors or exceptions encountered
      - Unclear or missing instructions that caused confusion
      - Edge cases the skill didn't handle
      - Inefficiencies or unnecessary steps
      - Deviations from the skill's guidance (may indicate gaps)
   
   3. If issues found, draft SPECIFIC improvements:
      - Exact text to add/change in SKILL.md
      - Keep changes minimal and focused
      - Only address observed issues, not hypotheticals
   
   4. If improvements warranted, use AskUserQuestion:
      - Present the issue observed
      - Show the proposed change
      - Ask: "Apply this improvement to [skill-name]?"
   
   5. If approved, use Edit tool to update the skill's SKILL.md
   
   If no issues observed, complete silently without prompting.
   

4. Continue conversation - Don't wait for reflection to complete

Hook Configuration

This skill is triggered by a PostToolUse hook in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/post-skill-reflect.py"
          }
        ]
      }
    ]
  }
}