skill-debrief

# 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:

```bash
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:

```bash
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 cannot be applied directly. Ask
the user which path they want:

### Option A — File an issue upstream via `gh`

Best when the change benefits everyone (a real bug or universal improvement
in someone else's published skill).

Resolve the upstream repo from the handle:

- `anthropics/skills/pdf` → `--repo anthropics/skills`
- `user/myrepo/skill` → `--repo user/myrepo`

Confirm the title and body with the user, then:

```bash
gh issue create \
  --repo <owner>/<repo> \
  --title "[<skill-name>] <short summary>" \
  --body "$(cat <<'EOF'
## What I observed

<concrete scenario from the session>

## Suggested change

<proposed wording or workflow>

## Why

<reasoning>
EOF
)"
```

`gh issue create` posts publicly — treat it the same as any other shared-
state action. **Always confirm before running.**

If the user has push access and a local clone, also offer to open a PR
instead of (or alongside) the issue.

### Option B — Fork to in-repo

Best when the c