Reflection
Capture feedback and failed tool calls into durable agent rules in AGENT.md or CLAUDE.md and tighten skill definitions over time.
Overview
Reflection is a journey-wide agent skill that turns user feedback and tool failures into confirmed updates to AGENT.md, CLAUDE.md, or skill files—usable whenever a solo builder needs to lock in preferences before the age
Install
npx skills add https://github.com/davidkiss/smart-ai-skills --skill reflectionWhat is this skill?
- Five-step ritual: analyze conversation → identify patterns → propose one change → confirm with user → apply only after a
- Stores recurring preferences and project rules in AGENT.md or CLAUDE.md for Claude Code–style workflows
- Proposes concise skill-definition diffs when gaps or inefficiencies show up in real use
- Triggered on explicit user feedback, style requests, and tool-call failures for self-improvement
- One-at-a-time changes to avoid noisy bulk edits to skills or memory files
- 5-step process: analyze, identify, propose, confirm, apply
Adoption & trust: 673 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You correct the agent or watch tools fail, but those lessons vanish in chat history instead of becoming durable rules or better skills.
Who is it for?
Solo builders maintaining a skills folder and CLAUDE.md/AGENT.md who want one confirmed change per reflection cycle after feedback or failures.
Skip if: Runs where you want automatic silent edits to skills or memory without user confirmation, or one-off tasks with no ongoing agent setup.
When should I use this skill?
MUST use when the user provides feedback, asks to do things a certain way, or when a tool call fails—for self-improvement and storing preferences in AGENT.md or CLAUDE.md.
What do I get? / Deliverables
After a confirmed proposal, preferences land in AGENT.md or CLAUDE.md and skill gaps get a single reviewed diff so the next session starts from updated procedural knowledge.
- One confirmed addition to AGENT.md or CLAUDE.md, or one reviewed skill diff
- User-facing proposal text before changes are applied
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
After the user insists on pnpm-only commands, reflection proposes one line for CLAUDE.md before touching package scripts.
When a test-runner tool fails twice, reflection suggests a concise addition to your testing skill’s invokeWhen section.
Recurring deploy-script errors trigger a single preference about always dry-running infra changes first.
Support-tone feedback becomes a stored rule so lifecycle emails match your brand voice.
User rejects a scope outline format; reflection captures the preferred template in AGENT.md for future plans.
How it compares
Use this meta ritual instead of re-pasting the same instructions every chat; it is not an MCP server or a code-review checker on your app repo.
Common Questions / FAQ
Who is reflection for?
Solo and indie builders using agentic IDEs who maintain SKILL.md libraries and AGENT.md or CLAUDE.md preference files and want systematic self-improvement from real sessions.
When should I use reflection?
During Build when tuning agent-tooling, during Ship when review or test failures reveal process gaps, during Operate when production tool errors recur, and anytime the user gives explicit feedback or asks for a consistent working style.
Is reflection safe to install?
It is designed to propose changes before writing, but it can edit filesystem content once you confirm—review the Security Audits panel on this Prism page and your repo backup practices before enabling auto-apply workflows.
SKILL.md
READMESKILL.md - Reflection
# Reflection Skill ## Overview This skill is used to learn from interaction with the user and failures in tool calls. It analyzes what worked, what didn't (tool failures), and identifies recurring patterns or explicit user preferences that should be formalized. ## Objectives - **Improve Skills:** Identify gaps or inefficiencies in existing skill definitions and propose concise updates. - **Store Preferences:** Capture user preferences, project-specific rules, or recurring instructions in a `AGENT.md` or `CLAUDE.md` (when used in Claude Code) file. ## Process 1. **Analyze:** Review the conversation history, tool calls, and any failures or corrections from the user. 2. **Identify:** Determine if a specific behavior should be codified in a skill or if a user preference has emerged. 3. **Propose:** Formulate a single, concise change. - If updating a skill, show a diff of the proposed change. - If adding a preference, show the proposed addition to `CLAUDE.md`. 4. **Confirm:** Present the proposal to the user and ask for explicit confirmation without making any changes first. 5. **Apply Changes:** Once user confirmed the changes, only then apply them ## Guidelines - **One at a time:** Only propose one change per invocation to maintain focus and allow for careful review. - **Conciseness:** Keep changes as brief as possible. Often a few words are enough to clarify a requirement or fix a common mistake. - **Accuracy:** Ensure the proposal directly addresses a real issue or preference observed in the session. - **Specificity:** Think how you could make the learnings more generic to apply to other use cases, but don't make the changes too generic so that it would not address the original learnings - **Failure Analysis:** Pay special attention to tool failures or when the user has to correct your approach. These are primary candidates for reflection. - **Conflict Resolution:** If a proposed change conflicts with details of an existing skill or user preference, propose a resolution that best serves the user's current intent.