AI Review Skills

View saved version →

---
name: documenting-with-sources
description: Common conventions for writing Markdown documents that cite external sources (survey reports, paper explainers, and any deliverable that surfaces facts from outside). Defines mandatory citation, in-text reference format, quotation-versus-prose separation, the ban on fabricated associations, and the source-list format. Referenced by survey, paper-details, and any skill that produces sourced output.
---

# Documenting with Sources

Common conventions for writing Markdown documents that pull from outside sources. Apply to any deliverable that surfaces facts taken from elsewhere — survey reports, paper explainers, and similar.

## Cite every factual claim

Every factual claim in the deliverable must carry a citation. A claim with no citation cannot be verified, and is worthless as a documented finding. If a claim cannot be tied to a source, mark it explicitly (e.g. "citation not confirmed"). Do not slip uncited claims in silently.

## Reference format

- In-text references take the shape `[label (YYYY/MM), location]`. How to fill the `label` slot (publication name, author short-form, position-only for the paper under review, etc.) is decided by the calling skill.
- Do not use bare numeric references such as `[1]` or `[2]`. Numbers alone force the reader to bounce between text and source list; readability drops.
- For the formatting of quotation blocks themselves (code-block fencing, original-and-translation pairing, where to place the source reference, anti-patterns), follow the `writing-quotation` skill. Read `writing-quotation` before drafting.

## Quotation vs prose

- Keep quotations and prose (the writer's own summary or interpretation) visually and structurally separate. Even when not quoting, write in a way that prevents the source's claim and the writer's interpretation from blending.
- When quoting a source written in a language other than the writer's working language, place the translation alongside the original inside the same code block (see `writing-quotation`).

## No fabricated associations or interpretations

Do not write interpretations, speculation, or associations that the source itself does not contain.

- Do not invent connections such as "this relates to X", "this could be applied to Y", or "this suggests Z" when the source does not say so.
- Do not import context from the surrounding conversation or the calling project into the body of the document. Descriptions of a source must stay within the source's own content.
- Good: "Main criticism: even with flipped labels, accuracy does not always drop, and the text-gradient is mathematically distinct from classical gradient descent" (states what the source actually says).
- Bad: "Relation to AI writing improvement: feedback-based improvement is mathematically different from gradient descent..." (the source does not say this; the connection is fabricated from conversation context).

## Source-list format

The source list at the end of the document uses this format:

`[label, YYYY/MM] Author. "Title." Publication. URL`

Do not use the `- [n]` list format.

View saved version →

---
name: explain
description: Conventions for writing a Markdown explainer that walks the reader through a concept or system. Lays out term-list formatting, Mermaid diagram rules, granularity expectations, and a fixed five-part structure. Use when the user asks for an explainer, a concept write-up, a glossary section, or otherwise wants a system or idea documented for another reader.
---

# Explainer Document Conventions

## Term handling

- Put a term list at the top of the document in table form (`| Term | Description |`). Every specialised term used in the body must be defined in this list at first occurrence.
- A term-list entry defines what the term *is* in one or two sentences. The functional or behavioural detail goes in the body, not in the term list.
- Even widely recognised proper nouns (industry-standard product names, infrastructure components, etc.) get defined here. Assume the reader does not know them.
- When defining a compound term, define the constituent words too. If the compound has three words, give all three their own entries — readers cannot be expected to infer one from another.

## Diagram conventions

- Use Mermaid for diagrams. Do not use ASCII art.
- Every node label is a term that exists in the term list. Do not introduce a new term inside a diagram.
- Do not put `<br/>` inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with ` / ` or shorten the text to fit one line.
- For diagrams with four or more nodes, or where any label is long, use `graph TD` (top-down). `graph LR` (left-right) collapses long-label graphs into an unreadable horizontal strip.

## Granularity of the description

- Do not gloss details with vague language. Subjects, objects, and verbs must be explicit.
- A phrase like "A uses B to do X" must specify what A is and why A is needed for X.
- Avoid vague verbs like "receives" or "passes". Spell out who does what to bring the state about (e.g. "receives the address" → "the platform allocates the address automatically").
- Do not require the reader to make a leap between steps. Every step's causal connection to the next is explicit.
- Describe the mechanism in its general form first; tie it to specific named instances afterwards as "in case X, ...". Do not anchor the whole description to a single proper-noun example.

## Structure

1. Term list
2. Background (why this thing is necessary, or what problem it addresses)
3. Mechanism (how it works — includes the diagrams)
4. Concrete steps (commands, procedures, or worked examples)
5. Current state (where things stand today — for ongoing systems)

View saved version →

---
name: html
description: Explicitly invoked only. 概念・仕組み・調査内容をHTMLで説明する。通常回答やMarkdown依頼では自動実行しない。
---

# HTML による説明ドキュメント

明示指定時だけ実行する。最初に `../../references/runtime-capabilities.md` を読み、実際の能力を確認する。

## 文章

説明内容と日本語表現を補うため、次のスキルの併用を推奨する。

- `explain`：概念や仕組みを説明するときの用語定義、説明の粒度、構成
- [`japanese-tech-writing`](https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d)：日本語の技術文書、記事、解説文の構成と文章規範
- [`cognitive-rhythm-writing`](https://gist.github.com/k16shikano/eb2929f13ed19c97188393d297be8432)：読み物としての緩急が必要な長文の文章規範

いずれも推奨スキルであり、`html` の必須依存ではない。

## 成果物

- HTML を作る
- ビルドなしでブラウザが直接描画できる状態にする
- 保存先が指定されている場合は従う。指定がなければ現在の作業ディレクトリへ保存する
- ファイル名は `{yyyymmdd}-{内容を表すケバブケース}.html` とする。既存ファイルの更新では名前を変えない
- 個別の文書管理システム、メタデータ、Viewer、公開先に関する規則は、このスキルを参照する上位スキルの指示に従う

Work Local / Work Cloud / 不明環境ではCSSと最小JSをインライン化し、利用可能な画像をdata URIにした単一HTMLを既定とし、CDNを必須にしない。Codex Localでは共有CSS/JS/相対画像を再利用でき、要求時は単一HTMLも作る。方式と制約を成果物に記録する。

## デザインシステム

作成前に `design-system/component-samples.html` を確認する。コンポーネント集は `design-system/document.css`、数式コピー機能は `design-system/math-copy.js` を正とする。

既定では、成果物と一緒に必要なファイルを配置し、次の相対パスで読み込む。上位スキルが共有アセットのパスを指定した場合は、その指定を優先する。

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Ubuntu+Sans:wght@400;500;700&family=Noto+Sans+JP:wght@400;500;700&family=Ubuntu+Mono:wght@400;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="./design-system/document.css">
<script src="./design-system/math-copy.js"></script>
<script async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script>document.addEventListener("DOMContentLoaded", () => hljs.highlightAll());</script>
```

主要規則は次のとおり。

- 背景は `#FAF9F6`。部品は白地、黒罫線、角丸を基本とする
- 自然言語は Ubuntu Sans と Noto Sans JP、コード・URL・日付は Ubuntu Mono を使う
- 有彩色はリンク青 `#2990DA` とアクセント赤 `#D63A2F` に限定する
- 赤い強調は原則として 1 ページ 1 箇所までとする
- シンタックスハイライトとコード差分の色は、意味を区別する機能色としてこの制限の対象外とする
- 余白は上下左右の均衡を保つ
- 引用は `.mb-quote` を使い、原文と訳文を同じ文字サイズ・色で上下に並べる
- `.mb-chip` は並列の固有名や分類名の列挙にだけ使う
- 絵文字や矢印文字を図記号として使わない。必要な記号はインライン SVG で描く
- 表は短い対応関係に使い、3 列までを基本とする
- 行見出しのセルには `.mb-rowlabel` を付け、語中の折り返しを防ぐ
- コード差分は `pre.mb-diff` を使い、変更理由を散文で説明してから必要な断片を示す
- ページ固有の `<style>` は図の配置調整など最小限にとどめる

## 構成とフォーマット

説明対象に合わせて、並置、図解、タイムライン、要約、折りたたみを使い分ける。
一方向の単純な手順を、必要性なくフローチャートにしない。

基本構成は次の順とする。

1. 背景と要点
2. 本論
3. 具体例
4. 補足・限界・関連事項

h1 とリード文の後に `.mb-toc` の目次を置き、各 h2 に対応する `id` を付ける。

### 用語リスト

専門用語は本文の初出で定義する。
用語リストは、複数箇所から参照する用語がある場合だけ設ける。
用語リストの位置は文書ごとに変更しない。
ブラウザ幅 1400px 以上では、本文右側の専用欄へ表示する。
ブラウザ幅 1399px 以下では、本文末尾へ表示する。
配置の切り替えは共有 CSS だけが担当し、用語リストによってヘッダー、リード、目次、要約、本文の幅を縮めてはならない。
マークアップは `aside.mb-glossary` と `dl`、`dt`、`dd` を使う。
正解例は `design-system/component-samples.html` を参照する。

## 図

- `.mb-figure` は、画像・SVGなどの視覚資料とキャプションを一つにまとめる外枠である。特定の図形や「矢印で結んだ箱」を意味しない
- `.mb-figure-frame` は視覚資料の表示面、`figcaption` は図番号・説明・出所の表示領域として使う
- 原典に重要な図がある場合は、出所を明示して引用する
- 原典の図があるのに模倣図を作らない
- 自作図はインライン SVG とし、アスキーアートを使わない
- 黒一色の線画を基本とし、`.mb-figure-frame` に載せる
- ノード数が多い場合は縦方向を優先する
- 矢印が交差する構成を避ける
- 単なる直列手順は番号付きの説明として表現する

## コード

- Highlight.js を必ず読み込み、言語に応じたシンタックスハイライトを適用する
- `pre code` には `language-javascript`、`language-python`、`language-html` などの言語クラスを必ず付ける
- ハイライトしないテキストには `language-plaintext` を付ける
- 独自の色付けでコードを装飾せず、`document.css` の `.hljs-*` 規則を使う
- `pre.mb-diff code` には `nohighlight` を付け、差分専用の色と行頭記号を使う

## 数式

- MathJax 3 を使う
- インライン数式は `$...$`、ディスプレイ数式は `$$...$$` とする
- ベクトルと行列は `\boldsymbol{...}` を使う
- スカラー、添字、集合名は装飾しない
- 名前付きの演算は `\mathtt{...}`、標準 LaTeX コマンドはそのまま使う
- `math-copy.js` により、すべての数式から LaTeX 原文をコピーできるようにする
- ページ側で `window.MathJax` を再定義しない
- 未知のコマンドを別記法へ勝手に置換しない

## 印刷と PDF

印刷対応は `document.css` の `@media print` を使う。
PDF 化はユーザーから明示的に依頼された場合だけ `render-pdf.sh` を実行する。

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: html-review
description: Explicitly invoked only. Convert canonical Markdown, JSON, Evidence, and test results into a human-readable HTML snapshot without making HTML the source of truth.
---

# HTML Review

Render an integrated Review Packet for human review. This projection layer does not research, judge correctness, launch agents, approve, replace tests, mutate canonical inputs, publish, or act as an agent return contract. Invoke only by explicit skill selection, never for ordinary HTML/Markdown/JSON responses.

Read `references/review-packet.schema.json` and `../../references/runtime-capabilities.md`. JSON and referenced Markdown/Evidence/tests remain canonical; HTML is `derived_snapshot`. Preserve wording, IDs, paths, URLs, timestamps, citations, verification and test states. Render absent optional values as `未提供`/`未確認`; never invent or silently omit. Reject missing/invalid canonical packets before rendering.

Keep conclusion, P0/P1, Blocked, Warning, Human Decision, and unresolved items expanded. Use semantic text, not color alone. Escape all input; do not runtime-fetch. Work/unknown outputs one offline HTML with inline CSS/JS and data-URI images (or locator plus `画像は未埋め込み`). Codex Local may reuse relative shared assets and must retain a portable option. Use one HTML writer.

When Python exists: `python scripts/render_review.py <packet.json> <output.html>`. Otherwise fill `assets/template.html` under identical rules. Validate all IDs/locators/citations/quotes/statuses, unchanged canonical hashes, no external dependencies, and truthful audit mode. Report HTML and canonical paths together; agents continue exchanging the packet, never HTML.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: paper-details
description: Produce a detailed Markdown explainer of an academic paper. The skill aims for faithful description, not critical review. Section structure mirrors the original paper, equations render as LaTeX with variable tables, citations to the paper under review use position only, and citations to other works use author-short form. Use when the user asks for a detailed paper write-up, a thorough paper explainer, or invokes "paper details". Depends on documenting-with-sources and writing-quotation.
---

# Paper Details

Conventions for producing a detailed Markdown explainer of an academic paper. The aim is faithful description, not critique. First read `../../references/runtime-capabilities.md` and detect PDF, filesystem, Python, uv, image-output, and subagent capabilities.

Before analysis, obtain `product` and `execution_location` from explicit task or host metadata and record them separately. Filesystem, Python, or shell availability does not prove Codex Local because Work Local can expose the same tools. If metadata is absent, record `Unknown`.

This skill follows the shared sourced-writing conventions defined in `documenting-with-sources`. Read `documenting-with-sources` before drafting.

## 1. Deliverable structure

### 1.0 Output location

Write the explainer as a `.md` file under the project's `reports/` directory, where "the project" is the root that contains the source paper PDF. Create the directory if it does not exist.

- Path: `{project-root}/reports/{paper-filename-base}.md`
- Example: if the PDF is at `/path/to/project/papers/foo.pdf`, the output is `/path/to/project/reports/foo.md`

Do not write next to the PDF, and do not write at the project root. Do not ask the user for the output path — determine it mechanically by the rule above.

### 1.1 Opening

In this order:

1. Title (`# {paper title} — Detailed Explainer`)
2. Bibliographic info (authors, affiliations, venue, year, arXiv/DOI, URL)
3. Full abstract — quote the original in a code block per `writing-quotation`; if the original is in a non-working language, place the translation alongside as a separate paragraph in the same block.

### 1.2 Body section structure

The body's section structure follows the paper's. If the paper has Section 1 Introduction, Section 2 Method, Section 3 Results, ..., the explainer uses the same order and the same headings.

Add explainer-only sections (e.g. "Strengths of the paper", "Limitations of the paper", "Source list") *after* the paper's own section structure.

### 1.3 Bullet lists vs prose

Pick the form by the nature of the content.

- Bullet lists fit enumerations of parallel items — variable lists, definitions of evaluation metrics, table-column descriptions, comparison points between methods, etc. When the content is genuinely list-shaped, the prose form blurs the boundaries between items.
- Prose fits relationships, causal flow, contextual explanation. When the reader needs to understand why items appear together or how they form a single argument, prose is what holds it together.

### 1.4 Figures and tables: extract as images

Never reconstruct a figure or table from scratch (no hand-written HTML tables, no redrawn SVG figures). Extract them as images from the source paper and insert those images into the deliverable (`.md` or HTML). Hand reconstruction introduces transcription errors and loses the original layout — bold, underline, colour-coded legends — so it is forbidden.

When Python, `uv`, PyMuPDF, and file output are available, use the bundled script:

```
uv run {this-skill-dir}/scripts/extract_images.py <PDF path> --out {project-root}/images-from-papers
```

- The script finds `Figure N` / `Table N` captions in the PDF and clip-renders the figure/table region directly above each caption — the bounding box of vector drawings, rules, and embedded images — at 300 dpi. Figures and tables are usually drawn as vectors with no embedded raster, so extraction is region rendering, not pulli

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: survey
description: Investigate a topic across papers, articles, social-media posts, and industry signals, then deliver an indexed Markdown report. Use when the user asks to investigate, survey, gather sources, build an index, collect evidence, round up references, or otherwise wants a thorough cross-source roundup on a specific topic. Depends on documenting-with-sources and writing-quotation.
---

# Survey

Gather sources from the web, papers, social media, and industry on a specific topic, and produce an indexed Markdown report. First read `../../references/runtime-capabilities.md`.

This skill follows the shared sourced-writing conventions defined in `documenting-with-sources`. Read `documenting-with-sources` before drafting.

## Quality criteria

Apply to every source.

- Prefer trustworthy sources (peer-reviewed papers > official blogs > major industry media > personal blogs).
- If the author is an individual, list their affiliation and role. If unknown, look it up.
- For papers, in addition to bibliographic info (authors, affiliations, venue, year), include citation count.
- Always attach a URL.
- Always attach a date.
- Treat official documentation and third-party articles as different reliability tiers. Do not mix them; the reader must be able to tell which is which.

## Prose structure: Assertion-Evidence form

Write the body in Assertion-Evidence form — claim first, then evidence.

1. Prose: the writer states the claim or summary in their own words first.
2. Immediately after, a code-block quotation from the source backs up the claim, formatted per `writing-quotation`.
3. On the line after the closing fence, place the source reference `[source-name (YYYY/MM)]`.

The reader grasps "what is being said" first, then checks "what is the basis". The reverse order (quotation first, claim later) is forbidden — the reader cannot tell what the quotation is for until they have read past it.

Bad example (quotation first):

```
The standard recipe of pretraining on huge corpora and then running classical preference-label RLHF is now widely treated as obsolete.
```

[industry-tracker (2026/03)]

The mainstream has shifted to a modular post-training stack.

Good example (claim first):

The classical RLHF pipeline (human preference labels → reward model → PPO) is no longer used in leading models; it has been replaced by a modular stack that separates concerns.

```
The standard recipe of pretraining on huge corpora and then running classical preference-label RLHF is now widely treated as obsolete. Every leading model released in the past year uses a different post-training stack.
```

[industry-tracker (2026/03)]

## Source-reference label

Within the `[label (YYYY/MM), location]` structure defined in `documenting-with-sources`, the survey skill fills the label slot with the publication or source name (media name, site name, etc.). The location is omitted when it cannot be pinned down.

## Heading-content alignment

Section headings and the items placed under them must match exactly.

- If a heading is "human-side guardrails", only human conduct and discipline goes underneath. Tooling and CI/CD belong under a separate heading.
- If a heading is "failure cases", do not mix in success stories or recommendations.
- If a source spans multiple angles, either split it across the relevant sections, or place it under the most appropriate one and add an explicit note about the other angles.
- Before finalising, walk every heading and check that everything underneath it actually belongs there.

## Output destination

Write the deliverable to `{CWD}/reports/` as a `.md` file. Create the directory if it does not exist. Sub-agents that emit intermediate artefacts use the same directory.

## Workflow

1. From the user's request, identify the claim or hypothesis and the collection scope.
2. Design search queries for the scope (in multiple languages where appropriate).
3. Use parallel subagents by angle when available; otherwise investig

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: writing-quotation
description: Formatting rules for quoting external sources inside Markdown. Use fenced code blocks, pair original and translation, and place labeled source references after the fence. Use whenever writing or editing quotation blocks.
---

# Writing Quotation

Formatting rules for quoting external sources inside a Markdown document. Other skills that produce sourced deliverables (`survey`, `paper-details`, and similar) reference this one.

## 1. Why quote the original

A summary alone does not let the reader judge whether the writer's reading of the source is correct. Placing the original alongside lets the reader cross-check the writer's interpretation against the source itself. Quotations and prose (the writer's own summary or interpretation) must stay visually and structurally distinct.

## 2. Quotations always go inside code blocks

Quote external sources inside a fenced code block, regardless of content type — prose, prompt templates, code, XML-tagged text, anything. Do not use the blockquote syntax (`>`).

## 3. Structure of a quotation block

A quotation block has the following shape.

- Opening code fence
- Original text
- One blank line
- Translation into the writer's working language (only when the source is in a different language)
- Closing code fence
- The source reference `[label (YYYY/MM), location]` on the line immediately after the closing fence

Rules:

- Original and translation sit together inside the same code block.
- One blank line separates them.
- Do not insert a horizontal rule (`---`) between original and translation.
- Do not move the translation outside the code block. Do not put it in parentheses next to the original.
- The source reference belongs on the line after the closing fence as an independent line. Never inside the code block.

## 4. Examples

### 4.1 Same-language quotation

When the source and the writer share a working language, no translation is needed:

```
Composability is the property by which a system's behaviour is determined by the behaviour of its parts and the rules under which they are combined.
```

[example-handbook (2026/04), Section 2.1]

### 4.2 Cross-language quotation

When the source is in a language other than the writer's working language, place the translation as a separate paragraph inside the same code block:

```
Le sens d'une expression complexe est déterminé par le sens de ses constituants et par les règles qui les combinent.

The meaning of a complex expression is determined by the meaning of its constituents and the rules that combine them.
```

[example-handbook (2026/04), Section 2.1]

### 4.3 Prompt-template quotation

Prompt templates use the same rule. Wrap inside a code block; place the source reference after the fence.

```
Human: You are an assistant who summarises research papers. The paper is enclosed in <paper> tags. Produce a summary enclosed in <summary> tags. <paper>P</paper> Assistant:
```

[example-prompt-library (2026/04), template 03]

### 4.4 Short-form role markers in translations

When translating a prompt template (Human/Assistant style), the translation side may abbreviate role markers to reduce cognitive load and to make it easier to tell original from translation at a glance.

- `Human:` → `H:`
- `Assistant:` → `A:`

Keep the original side unabbreviated (`Human:` / `Assistant:` in full). The trailing `Assistant:` at the very end of a chat template (the position that signals where the response begins) carries structural meaning and may be left as `Assistant:` on the translation side as well.

## 5. Source-reference format

Format: `[label (YYYY/MM), location]`.

- `label`: an identifier for the source. The calling skill decides the convention (author short-form, publication name, etc.).
- `(YYYY/MM)`: year and month. Do not include the day. If only the year is known, use `(YYYY)`.
- `location`: where in the source the cited passage lives (`p.4`, `Section 3.1`, `Figure 2`, `(15)`, `opening`, `final paragraph`

Preview of the first 4,000 characters. Read full instructions →