Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

skill-debrief

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).

computerlovetech · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add computerlovetech/agr --skill skill-debrief

About this skill


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:

CaseSource locationUpdate 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 repoCannot 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

Read the complete source ↗