writing

Savant verdict: Pending analysis

Imported from the source hub; Savant's analysis is still running.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• No license declaredConfirm you may reuse this skill before importing it into your repository.

SKILL.md

---
name: writing
description: 文章を書く・推敲するときに読む。ドキュメント、コメント、コミットメッセージ、PR 本文、記事のような説明文と、小説のような読み物が対象である。「AI っぽい」「読みにくい」文章を直すときにも使う。
metadata:
  derived-from: >-
    https://github.com/masseater/claude-code-plugin/tree/2e0619b1ab620552764da5ea6e46b77a0dcfaa35/plugins/writing
    https://github.com/cursor/plugins/blob/837067b75aa20ab58d7b2a2f6c0531e37118c596/pstack/skills/technical-writing/SKILL.md
---

# writing

文章を書く、直すときの規範である。

- 読者である人間の読み方と考え方は humanity-and-humanness に従う
- 日本語の言い回しは philtzjp/skills の [`japanese`](https://github.com/philtzjp/skills/blob/main/.agents/skills/japanese/SKILL.md) に従う
- この skill の規範は、その上に足すものである

## この skill が必要な理由と達成したい状態

この skill が必要な理由は、AI が文を、読者に何を判断させるかからではなく、学習した説明文の形から反射的に組み立てることにある。そのため理由が欠ける。コードから導出できる陳腐化する情報が増える。反射的な読点が不自然な拍を作る。全文が同じ認知モードで平坦になる。さらに AI は、書いてあることをそのまま読み取れる自分を読者の模型にする。推測で補いながら読む人間には、項目が数えられず、流れに乗れず、読んでも頭に残らない文章になる。この癖は読者を疲れさせ、大事な判断基準を埋もれさせる。

この skill で達成したい状態は、読者が一度読むだけで書き手の判断とその理由を受け取り、最後まで読み進められる文章になっていることである。

## 大原則

規範は、文型や禁止事項として機械的に当てはめるものではない。先に決めるのは「どう直すか」ではなく「その修正で文章の何を守るのか」である。形式ではなく、文章が果たしている働きで判断する。

### 読み手の読み方に合わせた構成

人間は順に読み、読んだ順に理解を組み立てる。一覧して全体を把握してから詳細に入る。構成はその読み方に合わせる。

- 1 つの文書には 1 つの種類だけを入れる
- 規則を並べる前に、その規則がなければ何が起きるかを書く
- 題と冒頭だけで、何の文書で何を守るかが分かるようにする
- 何の文書かは短い文の段落で書き、守ることは箇条書きで並べる
- 並列の項目はリストにする。文章に畳まない
- 別のファイルや節への索引には、一行の要約を付ける
- 一文に置く独立した判断は 1 つにする
- 同じ段の見出しは、同じ問いに答える
- 見出しには話題名ではなく要点を持たせる。手順の見出しは動詞句、概念の見出しは名詞句にする

文書の種類は 4 つある。仕事のための手順、仕事のための事実である参照、理解のための説明、学習のための手順である。読み手は種類ごとに読み方を変えるので、手順の中に背景を、参照の中に説得を書くと、読み手は読み方を切り替えられない。混ぜたくなったら文書を分けてリンクする。

同じ段の見出しの観点が揃っていないと、読み手は一覧しても何を軸に分けてあるのか掴めない。規則の節と手順の節と対象の節を同じ段に並べない。

規則を先に並べて理由を後から添えると、疑問が立たないので流れが生まれない。必要な理由から達成したい状態、大原則、規則へ進む構成は、この流れを文書全体に作ったものである。

一文に判断が複数あると、人間は読み飛ばして推測で埋める。AI は全部を実行する。ここで両者の認識がずれる。

### 緩急の設計

[`rhythm`](references/rhythm.md) も読むこと。

密度の高い文章が退屈になるのは、情報が多いからではない。全文が同じ認知モードで書かれているからである。読者の認知モードを、観察する、迷う、確信する、確かめ直すのあいだで切り替え、常に「続きを読む理由」を残す。

- 緩急は情報量の増減ではなく、認知モードの切替として設計する
- 未回収の緊張を、常に 1 つは開いておく
- 完成した結論を解説する声ではなく、考えながら進む当事者の声で書く
- 拍、緊張、緩みの材料は、状況の側からだけ取る
- 装置は内容で実現し、宣言しない
- 拍を作るために文を削らない

緊張がすべて閉じた瞬間に、読者は読むのをやめられる。未回収の緊張とは、答えの出ていない問い、裏の取れていない確信、あとで返すと約束した答えである。

状況とは、対象世界の出来事、データ、発言、語り手の判断状態である。場面のない説明文では、対象そのものの性質と、読者が抱く推論や反問が状況にあたる。状況に材料がない位置は、何も足さず平坦なまま残す。本文自身を話題にした文でリズムを作るのは、規範の違反である。

「先に答えを半分だけ置く」のように、これからやる操作を述べた文は、それ自体が駄文である。装置が機能していれば、読者は装置の存在に気づかない。

範囲、観点、比較軸、未確定事項といった導入に必要な文脈を削って短くするのは、緩急ではなく欠落である。密度を上げる編集は、共有済みの文脈の上でだけ行う。

## 規範

説明文を書くときは、次もすべて読むこと。

- [`purpose-and-reason`](references/purpose-and-reason.md)。目的と理由を書く
- [`no-perishable-information`](references/no-perishable-information.md)。コードから導出できる情報を文書に複製しない
- [`punctuation`](references/punctuation.md)。句読点は役割の境界と、意味が確定する場所に打つ
- [`purpose-before-means`](references/purpose-before-means.md)。手段より目的を先に置く
- [`headings`](references/headings.md)。見出しと箇条書きは体言止めにする

## 用途

`usecases/` は特定の文章を書く手順である。

- [`ai-context`](usecases/ai-context.md)。SKILL.md、AGENTS.md、CLAUDE.md のように AI が読む文書を書く
- [`readme-md`](usecases/readme-md.md)。人間が使うかを決めて使い始めるための README.md を書く
- [`novel`](usecases/novel.md)。小説を書く