# Reflect > Deep reflection on the skill learning system itself. Analyzes what's working, what's stale, and proposes structural improvements. The meta-skill. - **Type:** Skill - **Install:** `agentstack add skill-meshjs-evolving-claude-skills-reflect` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [MeshJS](https://agentstack.voostack.com/s/meshjs) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [MeshJS](https://github.com/MeshJS) - **Source:** https://github.com/MeshJS/evolving-claude-skills/tree/main/.claude/skills/reflect ## Install ```sh agentstack add skill-meshjs-evolving-claude-skills-reflect ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Reflect — System Self-Improvement A periodic deep-thinking session about the skill learning system itself. Like a craftsperson stepping back to look at their workshop — not the work, but the tools and how they're organized. Run this when things feel off, when the system feels heavy, or just periodically to keep skills sharp and lean. ## Usage ``` /reflect # Full reflection across everything /reflect auth # Focus on a specific area ``` ## Arguments - `$0` (optional) - Focus area: a skill name, "patterns", "journeys", or "system" --- ## Step 1: Gather the Full Picture Read everything that makes up the learning system: ``` .claude/skills/*/SKILL.md — All skill definitions .claude/skills/_patterns.md — Shared cross-cutting knowledge .claude/skills/wrap-up/SKILL.md — The learning engine .claude/journeys/*.md — Recent session learnings (last 5-10) ``` Also check: - How many skills exist and their `updated` dates - Which skills have `.versions/` history (indicates they've been actively evolved) - Size of each SKILL.md (are any bloated?) --- ## Step 2: Analyze Through the Learning Lens For each skill, consider: ### Is it earning its context window cost? Every skill loaded into a session consumes tokens. A 500-line skill that's rarely used is expensive. Ask: - When was it last updated? (stale = potentially wasteful) - How specific and actionable are the instructions? (vague = not helping) - Are there sections that repeat what's in `_patterns.md`? (duplicate = remove from skill) ### Is it accurate? - Do the code examples match current codebase patterns? - Are file paths and import references still correct? - Have project conventions changed since the skill was written? ### Is it the right granularity? - Too broad? Should it be split? - Too narrow? Should it be merged with another skill? - Is there knowledge trapped in journeys that should be in a skill? ### Is `_patterns.md` pulling its weight? - Are there patterns in individual skills that should be shared? - Are there stale patterns that no longer apply? - Is there missing cross-cutting knowledge? --- ## Step 3: Check for Drift Compare skill instructions against the actual codebase: ```bash # Check if key files referenced in skills still exist # Check if import patterns match reality # Check if component/module names are current ``` Look for: - Skills referencing files that moved or were renamed - Code examples using old APIs or deprecated patterns - Checklist items that are no longer relevant --- ## Step 4: Assess the Learning Loop Itself Reflect on whether the system structure is working: - **wrap-up**: Is it doing its job? Are skills actually getting better over time? - **Learning notes**: Are `` comments being used during work? If not, why? - **Journeys**: Are they useful to future sessions or just noise? - **_patterns.md**: Is it being referenced and kept current? Look at recent journeys and see if the same mistakes keep recurring. If so, the learning loop has a gap — knowledge isn't reaching the right skill. --- ## Step 5: Present Findings Use `AskUserQuestion` to present findings organized by priority: ### Categories: 1. **Stale** — Skills or sections that are outdated 2. **Bloated** — Skills that have grown too large for their value 3. **Missing** — Knowledge in journeys that should be in skills 4. **Duplicate** — Content repeated between skills and `_patterns.md` 5. **Structural** — Changes to how the system itself works For each finding, propose a specific action: - "Remove section X from skill-name (moved to _patterns.md)" - "Update file paths in skill-name (module moved to new location)" - "Create new skill for Y (pattern appears in 3+ journeys)" - "Simplify wrap-up step N (too many substeps, never all followed)" --- ## Step 6: Implement Approved Changes Apply the changes the user approves. This might include: - Editing SKILL.md files - Updating `_patterns.md` - Creating new skills - Removing or merging skills - Restructuring the wrap-up workflow - Archiving stale journeys Update `updated` dates on any modified skills. --- ## When to Run This - Every ~10 sessions or when you notice friction - After a major project change (new framework, architecture shift) - When skills feel "off" — producing wrong or outdated guidance - When the skill system itself feels heavy or over-engineered This is NOT a frequent tool. It's the periodic "sharpen the saw" moment. --- ## Philosophy This skill exists because learning systems need to learn too. A carpenter's workshop evolves — tools get reorganized, broken jigs get replaced, the workbench gets adjusted. But the carpenter doesn't reorganize every day. They do it when things feel wrong, or when they step back and see the clutter. `/reflect` is that step back. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [MeshJS](https://github.com/MeshJS) - **Source:** [MeshJS/evolving-claude-skills](https://github.com/MeshJS/evolving-claude-skills) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-meshjs-evolving-claude-skills-reflect - Seller: https://agentstack.voostack.com/s/meshjs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.