AGENT SKILL

explaining-code

Explains code or code changes in plain language, briefly by default or in full for a reviewer. Use when the user says "explain this PR", or when asked to explain, ELIE, summarize, or break down a PR, diff, branch, file, function, or concept for someone new to the code. Not for how a whole subsystem works; use explaining-architecture.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 2
Forks
0

01 前言 Front Matter

name
explaining-code
description
Explains code or code changes in plain language, briefly by default or in full for a reviewer. Use when the user says "explain this PR", or when asked to explain, ELIE, summarize, or break down a PR, diff, branch, file, function, or concept for someone new to the code. Not for how a whole subsystem works; use explaining-architecture.
argument-hint
[elie] <PR, file, function, branch, or concept>

02 资源文件 4

03 SKILL.md 正文

Explaining code

Explain a specific change or piece of code to a reader new to it, at the Brief or Full depth.

When the question is how a whole subsystem works (its architecture, data flow, and file map), call the Skill tool with explaining-architecture instead. If that skill is not installed, explain at the chosen depth, scoped to the question. Without a Skill tool, follow the skill call rules.

Input

The request holds an optional depth token followed by the subject: a PR number or URL, a file path, a function or class name, a branch name, or a concept.

STOP when the request names no subject and the conversation makes none clear. Ask once what to explain, and do no work until the user answers. Explain what the code does, not what its docs claim, and report any disagreement per the docs and code rules.

Depth

  • Brief (the default): follow the Brief section below.
  • Full (ELIE): selected by a leading elie or eliet token, or by a request for ELIE, an explanation "for an engineer" or "for a reviewer", an "in depth" explanation, or the full explanation. Read full explanation and follow it instead of the Brief section.

Drop the depth token before reading the subject.

Brief

  • Lead with a one-sentence summary that a developer with no context on this area understands.
  • Use concrete nouns ("the order history page", "the login screen"), not abstract ones ("the component", "the module").
  • Use an everyday analogy only when one fits naturally.
  • Follow with 3 to 6 sentences that answer the implicit follow-ups: what the situation was before, what changed, and why.
  • The whole Brief reply is the lead plus those sentences, at most seven sentences in one or two paragraphs, with no headings, bold labels, or bullet lists. Count the sentences before replying.
  • Write more only on request.
  • Spell out and define an unavoidable term or acronym inline at its first use, as in "the SLA (service-level agreement) checker".
  • Cover what and why, not how.
  • Leave out the tests, reviewer notes, risks, edge cases, and implementation detail such as algorithms, comparisons, headers, status codes, and function names; those belong to Full.
  • If they would help, end with one line offering the full explanation.
  • Summarize the effect instead of listing every file touched.
  • Match the scope of the explanation to the question: asked about one function, explain that function, not the whole system.
  • Fit the sentence order to the subject. A PR's sentences run before, then after; a concept may be one paragraph; and a module overview may name its responsibilities in prose.

An illustrative Brief explanation of a PR:

The search page now remembers recent results for one minute, so repeat searches load instantly. Before, every search queried the database, even when the same query ran seconds earlier. Now a results cache (a short-lived in-memory copy of recent answers) is checked first, and the database is queried only on a miss. Results can be up to a minute stale, which the PR accepts because listings change rarely.

04 同仓库更多 Skills

bostonaholic
bostonaholic/skills

writing-system-prompts

Writes and reviews system prompts for AI tools, agents, chatbots, and LLM products using a fixed section order and a quality checklist. Use when the user says "write a system prompt", or when drafting a system prompt or auditing one for missing stop criteria, tool rules, constraints, or examples. Not for compressing an existing prompt; use improving-prompts.

★ 2
bostonaholic
bostonaholic/skills

writing-prose

Writes and edits prose for people in a plain, conversational, short house style with no em dashes. Use when the user says "write this up", or when drafting or revising documentation, READMEs, explanations, blog posts, or other human-facing prose. Not for prompts written for agents; use writing-system-prompts or composing-agent-prompts.

★ 2
bostonaholic
bostonaholic/skills

writing-acceptance-criteria

Writes or rewrites acceptance criteria until each is provable: one observable outcome with a named check that can fail. Use when the user says "write acceptance criteria", or asks to write, rewrite, or tighten acceptance criteria or a definition of done. Not for proving work meets them; use proving-claims.

★ 2
bostonaholic
bostonaholic/skills

summarizing-shipped-work

Summarizes the user's merged GitHub PRs for a timeframe into a grouped, linked shipped-work report with highlights, and offers to update a brag document. Use when the user says "what shipped?", or when asked what the user shipped (this week, last month, a quarter, since a date), for a status update, or to update a brag doc.

★ 2
bostonaholic
bostonaholic/skills

running-retros

Mines a session transcript, past agent sessions, or named sources such as PR review comments for durable learnings, then proposes approval-gated edits to skills, AGENTS.md, or docs and tracker issues. Use when the user says "retro", or when the user explicitly asks for a retrospective. Never infer from session end or friction.

★ 2
bostonaholic
bostonaholic/skills

learning-from-mistakes

Codifies the latest correction or mistake in the conversation as a short imperative rule in the project or global CLAUDE.md or AGENTS.md, after the user approves it. Use when the user says "learn from this mistake", or when the user asks to learn from a mistake, remember a lesson for next time, add a rule to CLAUDE.md, or not repeat a behavior. Not for a whole session; use running-retros.

★ 2