skill-reflect

name	skill-reflect
description	Use this skill to reflect on the skills I used this session, review this session for skill feedback, how did the skills perform, improve the skills I just used, capture skill friction from this session, check which skills had problems, give feedback on the skills I used, review skill performance, surface skill issues from today's work.
license	MIT

skill-reflect

Universal cross-agent skill for post-session reflection on distributed skill performance. Detects friction, classifies it, proposes a concrete fix and a verifiable eval, scrubs PII, and writes a local Markdown artifact. GitHub issue filing is available on an explicit second consent only.

Distributed skills = skills installed from a plugin, marketplace, or external repo — those with resolvable provenance outside the user's own project.

---

Purpose

Skills shipped via plugins or marketplaces have no feedback loop once deployed. When an agent follows stale guidance, retries a broken command, or works around a missing case, that signal disappears. skill-reflect captures it — with consent — and routes structured, PII-safe findings back to the skill's author. Evals are emitted alongside every finding so the author can verify a fix actually helps.

---

When to use

• At or near the end of a session in which one or more distributed skills were invoked.
• In response to a user request to review skill performance (explicit invocation).
• When a nudge from skill-reflect-auto surfaces a pending-review marker at session start.

When NOT to use

• For the user's own in-repo skills — unless the user explicitly scopes them in (e.g. scope.skills in skill-reflect.config.json or a direct verbal instruction to include them).
• For skill-reflect and skill-reflect-auto — always excluded (scope.excludeSkills).
• When no distributed skills were invoked in the session (nothing to review).
• To fix the skill yourself — produce feedback for the author; do not modify the skill.

---

Two consent gates

Gate 1 — Review consent. Before examining any session data, tell the user what you will read (skill names, tool outcomes, friction signals — never secrets or values) and what you will produce. Proceed only on explicit approval.

Gate 2 — Send consent. After the local artifact is drafted and the redaction preview is shown and confirmed, offer to file a GitHub issue. Ask once; if the user declines, write the local artifact and stop. Never auto-file.

---

6-Step Workflow

Step 1 · Consent + scope

Introduce the review. Describe the skills you intend to cover (default: all distributed skills in scope) and what the output will be. If a calling skill injected its own identity or a specific session id into the nudge, acknowledge that context and honor it as the scope; attribution confidence is higher when the caller self-identifies. Confirm the user wants to proceed before doing anything else. (See references/session-sources.md §Scope injection.)

Step 2 · Locate sessions and skill usage

Identify which distributed skills were active and their approximate time windows. On Copilot CLI this means querying the session store; on Claude Code / Gemini CLI it means reading the transcript JSONL; on Cursor and other Tier C hosts it means reflecting on the visible conversation only. Collect skill names and invocation counts only — never read secrets, credential values, or private file contents. See references/session-sources.md for host-specific recipes and generic skill-usage signals.

Step 3 · Detect friction

For each skill's active window, scan for friction signals: tool failures, repeated retries of the same call, error names (not values), workaround chains, and escalation to manual steps. Attribute a signal to a skill by proximity in the session timeline. Consult the pattern catalog before asserting a finding — friction may be the task's fault, not the skill's. See references/friction-rubric.md for all pattern definitions and detection heuristics.

Step 4 · Classify

For each confirmed friction signal, construct a FrictionFinding object (CONTRACT §3). Assign a pattern from the catalog, map it to a category, and score severity, confidence, and outcome. Apply the false-attribution caution: when causal attribution is uncertain, downgrade confidence to Possible and note the uncertainty in evidence. See references/friction-rubric.md (false-attribution caution) and references/skill-improvement-taxonomy.md (pattern→category mapping).

Step 5 · Propose fix and eval

For every FrictionFinding, write a proposedFix (a concrete, actionable change the skill author can make — add a case, correct a command, clarify a step) and a proposedEval in both the skill-creator evals.json format and the portable must_contain / must_not_contain form. The eval prompt should be a realistic task that exercises the proposed fix — but it must be an invented, analogous task, not the real one: it must exercise the skill's friction without disclosing the product, app type, or implementation where it was originally encountered (CONTRACT §0.3; references/privacy-scrub.md §2a). See references/eval-format.md for authoring rules and worked examples.

Step 6 · Scrub → preview → report

Paraphrase all findings (no PII, no verbatim excerpts, no absolute paths, no secrets, and no product/app/project names, app type, or implementation specifics — recast any reproduction detail as an invented, analogous scenario per references/privacy-scrub.md §2a). Run scripts/scrub.py as a deterministic backstop if available, passing any privacy.redactTerms as --term and privacy.extraScrubPatterns as --pattern. Show the full artifact text and a redaction summary to the user before writing anything; ask for explicit confirmation. Resolve the routing for each finding per references/provenance-routing.md. Write the local artifact to .skill-feedback/<YYYY-MM-DD>-<skill-slug>.md. Then, if destination mode is issue or ask, offer Gate 2. See references/privacy-scrub.md for scrubbing rules and references/reporting.md for the full artifact template and field-filling guide.

---

Default output

.skill-feedback/<YYYY-MM-DD>-<skill-slug>.md

<skill-slug> = skill name lowercased, non-alphanumerics collapsed to -. Example: my-ci-helper → .skill-feedback/2025-07-07-my-ci-helper.md

Config key artifactDir overrides the .skill-feedback/ base directory. Nothing is written until Step 6 confirmation is given.

---

Safety rules (enforced regardless of config)

Rule	Detail
No PII	Names, emails, tokens, keys, absolute paths, machine names, private URLs, verbatim transcript excerpts — never in any artifact
No domain leakage	Never reveal product/app/brand/project names, the app's type or purpose, or implementation specifics. Recast reproduction steps as an invented, analogous scenario (references/privacy-scrub.md §2a)
Redaction preview mandatory	Always show the full proposed artifact and a scrub summary before writing. privacy.redactionPreview is hard-true.
Verbatim excerpts forbidden	privacy.allowTranscriptExcerpts is hard-false. All content is paraphrased.
Consent before every write	Nothing written to disk; nothing filed as an issue until the relevant gate is passed.
Paraphrase, don't quote	Refer to tool/variable/error names, never their runtime values.

---

Session store and transcript availability (by host)

On Copilot CLI: the session store is queryable from inside the agent. Skill invocations appear as tool_requests rows; the store enables richer multi-session signals.

On Claude Code / Gemini CLI: a transcript JSONL is typically available via transcript_path. Parse it for SKILL.md loads, Skill tool calls, and nearby failures.

On Cursor, Windsurf, Codex CLI, cloud agents (Tier C): no store or transcript is accessible. Reflect on the visible conversation only. Findings may be fewer; lower confidence is normal.

Details and fallback rules: references/session-sources.md.

---

Reference files

File	Authored by	Contents
references/session-sources.md	M1	Host recipes, generic signals, scope injection
references/friction-rubric.md	M1	Severity/confidence/outcome; pattern catalog; false-attribution caution
references/skill-improvement-taxonomy.md	M1	Category definitions, typical fixes, pattern→category table
references/privacy-scrub.md	separate agent	Scrubber spec, redaction categories, paraphrase protocol
references/eval-format.md	separate agent	Eval authoring rules, both format examples
references/reporting.md	M1	Artifact template, field-filling guide, file naming
references/provenance-routing.md	separate agent	Skill-name→repo resolution; registry; fallback