Generic post-workflow self-reflection that any skill can invoke at the end of its run. Analyzes friction encountered during execution and produces advisory recommendations for improving the calling skill's SKILL.md. Use when a skill finishes (success or failure) and wants to capture improvement opportunities.
75%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.github/skills/skill-reflection/SKILL.mdA composable "after-action review" that any skill calls at the end of its workflow. It receives structured information about what happened and produces concrete, prioritized recommendations for improving the calling skill's SKILL.md.
This skill does not modify SKILL.md files automatically — it produces advisory output. The user decides what to apply.
The primary output is a structured reflection report. If memory capture, immediate fixes, or workflow resumption are needed, treat those as explicit caller-side follow-up actions after the report is produced.
Add this as the final step in any skill's SKILL.md:
### Step N: Reflection (composable)
Invoke the `skill-reflection` skill with the following context:
- **Calling skill**: `<skill-name>`
- **SKILL.md path**: `.github/skills/<skill-name>/SKILL.md`
- **Steps completed**: list each step with pass/fail/skipped
- **Friction notes**: any workarounds, retries, unexpected errors, or manual interventions
The reflection skill will analyze the run and produce improvement recommendations.Preferred invocation shape:
Run skill-reflection for <skill-name>.
SKILL.md path: .github/skills/<skill-name>/SKILL.md
Steps completed:
1. <step name> - PASS
2. <step name> - FAIL
3. <step name> - SKIPPED
Friction:
- <issue 1>
- <issue 2>
Run duration: <optional>This exact shape is not required, but it is the preferred caller format because it reduces follow-up questions and makes repeat-friction detection easier.
Run skill-reflection for azure-local-deploy.
Steps completed:
0. Prerequisites check — PASS
1. Docker build — PASS (took 4min, estimate was 2min)
2. ACR push — FAIL, Zscaler blocked. Used --insecure workaround.
3. App Service deploy — PASS after retry
4. Smoke test — PASS
5. Rollback — SKIPPED
Friction:
- Zscaler blocked ACR push on first attempt
- Docker build slower than documented estimateRun skill-reflection for branch-wrapup.
Steps completed:
1. Build — PASS
2. Typecheck — FAIL (3 errors), fixed, re-ran — PASS
3. Lint — PASS
4. Test — PASS
5. Security scan — SKIPPED (no scanner configured)
6. Code review — PASS
7. Commit — PASS
Friction:
- Typecheck errors were caused by a pattern the skill doesn't warn about
- Security scan step has no fallback when scanner isn't installedWhen invoked, follow these steps in order.
Extract from the caller's input:
| Field | Required | Description |
|---|---|---|
| Calling skill name | Yes | Which skill just ran |
| SKILL.md path | Yes | Where to find the skill definition |
| Steps + status | Yes | Each step with PASS / FAIL / SKIPPED |
| Friction notes | No | Free-text description of issues encountered |
| Run duration | No | Total wall time if available |
Normalize status variants such as "passed", "failed", "ok", or "done" to
PASS, FAIL, or SKIPPED before analyzing the run.
If the caller didn't provide structured input, ask:
What skill just ran, and what friction did you encounter?
Use this minimum-context rule:
SKILL.md path, friction notes, or run duration are missing.Before categorizing, walk through these prompts to surface friction that the caller may not have explicitly reported:
Add any findings to the friction list alongside what the caller already reported.
Before analyzing friction, evaluate whether the skill achieved its stated purpose. Read the calling skill's description field and ## Purpose section from its SKILL.md, then answer:
Goal achieved? — Did the run produce the output the skill's purpose describes? A skill can run flawlessly (all steps PASS) but still miss its stated goal — e.g., a research skill that creates notes but stops surfacing insights, or a digest that reports data but stops being actionable.
Ontological drift? — Has the skill's actual behavior diverged from its stated purpose over time? Signs of drift:
Value opportunities — Given what the skill actually does and what the vault needs, are there ways to increase its value?
Add findings to the reflection output as a new section:
Goal assessment:
Purpose achieved: [yes | partial | no]
Drift detected: [none | minor | significant]
Drift details: <what changed vs stated purpose>
Value opportunities:
V1. <opportunity description>
Impact: [high | medium | low]
Effort: [trivial | small | medium]
V2. ...Priority rules for drift:
Classify each friction point into one of these generic categories:
| Category | Description | Examples |
|---|---|---|
| Prerequisite gap | A tool, auth, or config needed but missing or misconfigured | CLI not installed, auth expired, env var missing |
| Command failure | A documented command failed and needed a workaround | Wrong flag, API changed, syntax error in script |
| Environment issue | Network, proxy, permissions, or platform-specific problem | Zscaler, firewall, file permissions, OS difference |
| Timing mismatch | Step took much longer/shorter than documented | Cold start, download, build time wrong |
| Undocumented error | Error message not covered in troubleshooting | New error not in the skill's error table |
| Missing step | A manual action was needed that isn't in the skill | Had to run an extra command between steps |
| Ambiguous instruction | A step was unclear and required interpretation | Vague wording, missing parameter, unclear order |
Read the SKILL.md to understand:
If SKILL.md path is missing but the calling skill name is present, say that the
path was not provided and continue with the rest of the reflection instead of
blocking the run.
Look for previous reflection output in the vault or in .github/sessions/:
Search for: "SKILL REFLECTION — <skill-name>"If those history sources are unavailable, say so explicitly instead of assuming there is no repeat friction.
If the same friction category + same step appears in a previous reflection:
Output using this verbose format:
--- SKILL REFLECTION — <skill-name> ---
Run summary: Steps 1-N completed | <X> passed, <Y> failed, <Z> skipped
Friction points: <count>
Friction encountered:
1. [Step X] <category>
What happened: <description>
Evidence: <error text, command output, timing, or observed symptom if available>
Confidence: <high | medium | low>
Workaround used: <what the user/agent actually did>
→ Recommendation: <specific change to SKILL.md>
2. [Step Y] <category>
What happened: <description>
Evidence: <supporting signal if available>
Confidence: <high | medium | low>
→ Recommendation: <specific change to SKILL.md>
Goal assessment:
Purpose achieved: [yes | partial | no]
Drift detected: [none | minor | significant]
Drift details: <what changed vs stated purpose, or "aligned" if no drift>
Value opportunities:
V1. <opportunity> — Impact: <high|medium|low>, Effort: <trivial|small|medium>
V2. ...
Prioritized recommendations for <skill-name>/SKILL.md:
R1. (P0 - breaking) <change needed to prevent failure next time>
Why this priority: <one sentence>
R2. (P1 - quality) <improvement to reduce manual steps or retries>
Why this priority: <one sentence>
R3. (P2 - nice) <minor doc, timing, or clarity improvement>
Why this priority: <one sentence>
Repeat friction: [none | list of issues seen before with dates]
Self-improvement rule:
If the same friction point appears in two consecutive runs,
escalate to P0 and flag as a required fix before the next run.
No SKILL.md changes made — recommendations are advisory.
To apply: tell Copilot "apply the <skill-name> reflection recommendations and fix the SKILL.md".
---Recommendation writing rules:
unknown, not provided, or not checked
explicitly instead of implying that nothing was found.Optionally append a short follow-up block after the advisory report when useful:
Caller follow-up:
- Memory capture: [required | optional | not needed]
- Immediate fix before next run: [none | P0 item]
- Resume parent workflow: [yes | no]Skip this follow-up block on clean runs unless the parent workflow explicitly requires memory capture or a resume signal.
If the invoking workflow's rules require durable memory capture and the Obsidian
path is available, the caller can save the friction + resolution after the
reflection report is produced. Use the obsidian skill's Agent Memory pattern:
@'
---
tags: [agent-memory, lesson]
source-skill: <calling-skill-name>
captured: <YYYY-MM-DD>
confidence: high
---
# Skill Reflection: <calling-skill-name> — <short friction summary>
## Context
<What skill was running, what step failed>
## Insight
<The key takeaway — what to do differently next time>
## Recommendations Applied
<List P0/P1 fixes that were applied to the SKILL.md>
'@ | python .github/skills/obsidian/scripts/obsidian.py create --path "Agent Memories/reflection-<skill-name>-<date>.md"Search first to avoid duplicates:
python .github/skills/obsidian/scripts/obsidian.py search "<skill-name> <friction-keyword>" --path "Agent Memories" --format jsonWhen reflection is triggered mid-run (not end-of-session), the invoking agent may use the advisory output to decide whether to self-heal before continuing the parent workflow:
This turns reflection from a post-mortem into a live self-healing loop.
| Priority | Meaning | Action |
|---|---|---|
| P0 - breaking | This friction will cause the skill to fail again next time | Must update SKILL.md before next run |
| P1 - quality | This friction causes retries, confusion, or wasted time | Should update SKILL.md soon |
| P2 - nice | Minor clarity or timing improvement | Update when convenient |
If the same friction point (same category + same step) appears in two consecutive runs, automatically escalate it to P0 regardless of original priority.
This prevents known issues from lingering as "nice to fix" indefinitely.
If a run completed cleanly with no friction:
--- SKILL REFLECTION — <skill-name> ---
Run summary: Steps 1-N completed | all passed
Friction points: 0
Goal assessment:
Purpose achieved: [yes | partial | no]
Drift detected: [none | minor | significant]
Drift details: <assessment even on clean runs>
Value opportunities:
V1. <any opportunities spotted, or "none — skill is delivering full value">
Repeat friction: none
✅ Clean run — no friction recommendations.
Skill is working as documented.
---Still log it if persisting to vault — clean runs are useful signal too.
❌ Auto-editing the calling skill's SKILL.md — always advisory
❌ Inventing friction that wasn't reported — only analyze what happened
❌ Generic advice ("add more docs") — recommendations must be specific and actionable
❌ Skipping the history check — repeat detection is the core value
❌ Running without knowing which skill called — always require the caller identity
❌ Treating follow-up actions as core output — memory capture and fixes belong to the caller workflow0xRabbidfly/Eric-Cartman
a524ec9
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.