/skill-debrief

name: skill-debrief
description: >
  Debrief an AI agent skill (SKILL.md) after using it — capture session
  feedback or a retrospective and fold it back into the skill. Use whenever
  the user says: "debrief the X skill", "let's debrief X", "retrospective on
  X", "feedback on X skill", "improve the X skill", "update the X skill",
  "let's revise X based on what we just did", "the X skill should also
  handle Y", "X didn't trigger when it should have", or otherwise wants to
  capture lessons from a session back into the skill that drove it. Handles
  in-repo skills (under skills/) by editing the source, committing, and
  re-installing via `agr upgrade`. Handles remote/upstream skills by
  offering to fork them in-repo or to file a GitHub issue via `gh`. Do NOT
  use for greenfield skill authoring (a separate concern — see
  `anthropics/skills/skill-creator`) or for installing / syncing / removing
  skills (use the `agr` CLI directly).

Skill Debrief

Capture lessons from a session into the skill that drove it. The default shape is **listen → propose → align → apply → re-install**.

When to use

Trigger when the user wants to debrief an existing SKILL.md based on what happened in the session. Examples:

• "debrief the X skill" / "let's debrief X"
• "retrospective on X" / "feedback on X"
• "improve the X skill" / "let's update X based on what we learned"
• "X skill should also handle …"
• "X didn't trigger when it should have"

Do NOT use this skill for:

• **Greenfield skill authoring.** Use `agr init` to scaffold a SKILL.md and

defer the body content to the user — or to a dedicated authoring skill such as `anthropics/skills/skill-creator` (`agr add anthropics/skills/skill-creator`).

• **Installing / syncing / removing skills.** That's plain `agr` CLI work

(`agr add`, `agr sync`, `agr upgrade`, `agr remove`).

Step 1: Identify the skill

Ask which skill is being improved if it isn't obvious from context. Then locate the source:

agr list                # see installed deps and short names
ls skills/              # in-repo source if present
cat agr.toml            # see whether the dep is local-path or remote

Two cases — they have different update paths:

| Case | Source location | Update path | |---|---|---| | **In-repo** (`{path = "./skills/<name>", type = "skill"}` in `agr.toml`) | `skills/<name>/` | Edit source → commit → `agr upgrade <name>` | | **Remote** (`{handle = "user/repo/<name>", …}`) | Upstream GitHub repo | Cannot edit directly — see Step 5 |

If the skill isn't installed at all but the user wants to improve it, ask whether to add it first (and which case applies).

Step 2: Receive feedback

**Listen.** The user invoked this skill because they have something to say — let them say it. Do not interrogate. Do not run a checklist of questions at them. Take in whatever they offer, in whatever shape they offer it.

Only ask a clarifying question if you genuinely cannot proceed without one (e.g. the user named a skill that doesn't exist, or two skills share the name and you need to disambiguate). Even then, ask the minimum.

Be **dynamic**. The user may surface things in any shape — a single sentence ("the description should also fire on X"), a structured list, or a ramble that you need to distill. They may also surface things outside the standard buckets below (rename a section, restructure `references/`, change output format, drop a deprecated workflow, fix a typo). Apply whatever the user actually says.

The buckets below are a mental map for *you* when distilling what you heard, not a checklist to recite at the user:

• **`description` / triggers** — under-fired or over-fired
• **Gotchas / boundaries** — a foot-gun the skill didn't warn about
• **Workflow steps** — missing, wrong, or out of order
• **References** — a topic kept needing more depth → new `references/<topic>.md`
• **Examples / output format** — vague where it should be concrete
• **Pruning** — outdated content that misled

Step 3: Propose changes

Summarize what you heard, then propose specific edits. Format:

> **Proposed changes to `skills/<name>/SKILL.md`** (and any references): > > 1. **Description** — add trigger phrase "…" (because: …) > 2. **Boundaries** — add: never X (because: discovered this in session) > 3. **New section "Y"** — describes the workflow that was missing > > Want me to apply these, revise, or add more?

For small edits, show the exact diff inline. For larger changes, summarize first and apply section by section.

**Wait for explicit user approval before editing.** "yes" / "go ahead" / similar. If the user revises, loop back to Step 2 or 3.

Step 4: Apply (in-repo case)

Edit the source file(s) under `skills/<name>/`. Then:

git status                        # confirm only the intended files changed
git add skills/<name>/
git commit -m "skill(<name>): <one-line summary>"
agr upgrade <name>                # re-installs into all configured tools, refreshes agr.lock
git add agr.lock
git commit --amend --no-edit      # or commit separately; match the repo's style

**Do not push.** Stop after the commit and let the user push when ready.

Commit message style

Use a conventional-commits-style scope:

skill(<name>): <imperative summary>

Examples:

skill(agr-cli): clarify upgrade vs sync for local paths
skill(agr-cli): add gotcha for same-repo siblings
skill(code-review): drop outdated linter pre-check

If the repo's commit style differs (check `git log --oneline -20`), match it.

Why `agr upgrade` and not `agr sync`?

`agr sync` only installs **missing** deps — it does NOT re-copy a local-path skill that's already installed. `agr upgrade <name>` re-copies it and refreshes `agr.lock`. Use `agr upgrade`.

(Equivalent: `agr add ./skills/<name> --overwrite`. Pick `upgrade` for consistency — it's the same verb used to refresh remote skills.)

Step 5: Apply (remote case)

If the skill is a remote dep, the change canno