菜单
Draw a code change or part of a codebase as an animated architecture or data-flow diagram. Use when opening or updating a pull request that touches more than one module, when asked to diagram, visualise or explain a change or a system, or when a reviewer needs the blast radius before the diff.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/harlan-zw/harlan-agent-kit --skill pr-lens命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | pr-lens |
| description | Draw a code change or part of a codebase as an animated architecture or data-flow diagram. Use when opening or updating a pull request that touches more than one module, when asked to diagram, visualise or explain a change or a system, or when a reviewer needs the blast radius before the diff. |
| user_invocable | true |
| argument-hint | [base ref, PR number, or path to diagram] |
Vendored from coldteadotai/pr-lens packages/agent-skill (MIT, see LICENSE). Adapted for this kit: pnpm dlx replaces npx, and the pull request rules below defer to the pr skill.
The pr skill calls this skill in Step 3 for every non-trivial pull request. Use it on your own when:
Skip it for one-file fixes, dependency bumps, formatting, and Markdown-only work. A diagram of a one-line change reads as noise.
Run the CLI from the task worktree. .pr-lens/ is scratch; never commit it.
PR Lens draws code as visually rich animated diagrams. It can represent diffs, architecture, data flows, and more.
The diff or code is represented as one JSON document (lanes, nodes, edges, ordered flows) and it renders the JSON as an animated SVG
Read the diff. When asked to represent a code change: git diff --find-renames <base>...<head>. The base is the merge base, not the tip of the base branch.
If not expressing a code diff, read the code to be visually represented
Write the document to .pr-lens/graph.json, following references/graph-document.md. references/example.graph.json is valid reference with three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree. Read it before you write your first one. It is quicker than reading the reference.
Validate, and fix
pnpm dlx @coldtea/pr-lens-cli validate .pr-lens/graph.json
Fix every failure and run it again. Do not render an invalid document; do not "work around" a failure by deleting the element it names.
Render.
pnpm dlx @coldtea/pr-lens-cli render .pr-lens/graph.json --theme dark
Render dark as the default theme unless explicitly requested. The SVGs, the manifest and drawn.graph.json land in .pr-lens/, which the CLI adds to the repository's .gitignore. Do not commit any of it. These files are rebuilt from the diff whenever anyone wants them again. Each SVG is named after its view, the theme and a content hash; manifest.json lists them by lens and view, so read the names from there or from the directory.
If the user asked for a diagram and nothing more, this is the end of the loop. If working in an environment that supports a visual way to display the image e.g., an in-app browser, an artifact, do so. Otherwise, tell them where the SVGs are and which one is the top view.
Attach, when there is a pull request to attach to. That means the user asked you to open a PR, asked for a diagram on one that exists, or you are opening a PR as part of changes made. Otherwise skip this step.
GitHub CLI uploads the diagram with the pull request. Write the body with a Markdown image pointing at the local file, then pass the same path to --attach. gh rewrites the reference to the uploaded asset and keeps the alt text you wrote:
Moves bulk sending off the per-recipient trigger and onto a batch endpoint.
The agent authors the document itself. Never run analyze. It sends the diff to a hosted model on a key, and this kit has none.
A reviewer should understand the change before reading the diff, so the diagram goes where they look first: the description, not a trailing comment. Open with one sentence on why the change exists, then the architecture diagram, then whatever proves the change works, such as a screenshot of the result or a recording of the interaction. Use one visual per idea. A diagram that needs a paragraph of explanation has a document problem; go back to step 2.
delta: "unchanged".Treat architecture views as a C4-inspired decision tree, not a checklist. One useful view is enough for a small change. Start with system context when the change affects a user, an external system or a system boundary. Use a container view for the affected applications, services, jobs, data stores and runtimes. Add a component child only when an affected container's internals matter. Do not add code-level views by default.
Every child moves down one level and covers a materially narrower scope. Skip empty, repetitive or speculative levels, and do not infer architecture from folder names alone. Two views should not carry substantially the same nodes and edges. Keep the unchanged direct neighbours that explain blast radius.
Keep data-flow views as separate roots rather than nesting them in the architecture tree. Set defaultOpen: true on the highest useful architecture view. Lower levels should normally keep the default, false.
Read references/graph-document.md before writing. The four failures that account for nearly everything:
| Code | What you did |
|---|---|
BROKEN_REFERENCE | an edge, a flow step or a view names an id you never declared |
INVALID_DOCUMENT | an invented field; the schemas are strict, unknown keys are rejected |
DUPLICATE_ID | two nodes, edges or views sharing an id |
UNSUPPORTED_SCHEMA_VERSION | schemaVersion is not the contract version installed |
Four rules cannot be expressed in JSON Schema and are checked only by the parser, so structured output alone does not make a document valid: referential integrity, a line range that ends before it starts, a self message whose endpoints disagree, and a patch whose two commits are the same. Always validate.
When someone says the diagram is wrong (a node is misnamed, a folder should not be on it, something sits in the wrong lane), do not edit the generated document. It is regenerated on every run. Write the correction into .github/pr-lens.yml, which is an overlay applied over fresh inference every time:
schemaVersion: 0.1.0
map:
rename:
- match: functions/src/broadcast/sendBroadcastBulk.ts
to: Broadcast sender
exclude:
- '**/*.test.ts'
lane:
- match: packages/broadcast-lib/**
lane: functions
references/config.md has the full format and the recipes. Validate it the same way: pnpm dlx @coldtea/pr-lens-cli validate .github/pr-lens.yml.
A match beginning with id: addresses one node exactly; anything else is a path glob matched against a node's file paths. Prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.
pr-lens render says so when a correction matched nothing, which is how a config that has drifted, because the file it named moved or was deleted, becomes visible instead of quietly doing nothing.
Everything you need is beside this page. Nothing here asks you to install a package first.
references/graph-document.md | the document, field by field: enums, limits, and where documents actually go wrong |
references/config.md | .github/pr-lens.yml, the correction overlay, in full |
references/example.graph.json | one complete document that validates, to read and to copy the shape of |
The same document ships as postmark-refactor.graph.json in @coldtea/pr-lens-schema, and the JSON Schema the validator enforces is published at https://unpkg.com/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json. Neither is something you need to fetch to write a document.
gh pr create --title "Batch broadcast sends" --body-file .pr-lens/body.md \
--attach .pr-lens/overview-dark-4f9bd6c1.svg
On a pull request that already exists, gh pr edit <number> with the same two flags puts the diagram in the description, and gh pr comment <number> puts it in a comment. Repeat --attach for each diagram the body references.
gh has three rules:
. An HTML <img> or <picture> is left as written, and the file is appended at the bottom of the body instead.--attach arrived in GitHub CLI 2.99. Check with gh --version before you write a body around it.Attach the views a reviewer needs and leave the rest in .pr-lens/: the top architecture view first, then a data flow if the change has a sequence worth following. A body with four diagrams reads worse than one with two, except the four are really needed to understand the change e.g., in the case of a complex feature or refactor.
When --attach is not an option, publish the SVGs somewhere durable and let the CLI compose the comment instead:
pnpm dlx @coldtea/pr-lens-cli comment \
--graph .pr-lens/drawn.graph.json \
--manifest .pr-lens/manifest.json \
--asset-base-url https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<dir>
--graph takes drawn.graph.json, not the document you wrote, because corrections change what the diagrams show and the CLI refuses a document its manifest does not describe. --asset-base-url is where you published the SVGs; leave it out and the markdown points at local paths no reader can fetch. The markdown goes to stdout, with each diagram as a <picture> pair; posting it is your business.