Skip to content

feat(writing-documents): extract the shared writing discipline - #20

Open
gitt510 wants to merge 2 commits into
mainfrom
extract-writing-documents
Open

feat(writing-documents): extract the shared writing discipline#20
gitt510 wants to merge 2 commits into
mainfrom
extract-writing-documents

Conversation

@gitt510

@gitt510 gitt510 commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Why

  • 形式の規律が build-readmebuild-pr-description に二重に定義されており、document 型を足すたびに複製が増える
    • 書き換え技法の悪例・良例が両 SKILL.md に verbatim で存在する(synchronize の2行と size/* の2行、各ファイル4行)
    • build-pr-description が本文で「build-readme と同じく、匂い狩り(denylist)ではなく」と複製であることを自認していた
    • 「3形式のみ」「1 bullet = 1 fact」「paragraph 禁止」「1 fact = 1 home」「完了チェックを機械的に検査する」が両者に重複していた

What

writing-documents

  • 判定方法(allowlist)・削除テストの形・3形式と paragraph 禁止・書き換え技法・1 fact = 1 home・session leak・共通の完了チェックを1箇所に持つ
  • document 型を持たない — allowlist の中身・section 骨子・fact の収集経路・削除テストの主体は呼び出し側が定義する
  • 呼び出し側との分担を table で宣言する
  • 呼び出し側は section を名指しして nest と理由節の例外を宣言できる
  • 単独でも trigger する(既存 draft から地の文・自己弁護を落とす依頼)

build-readme / build-pr-description

  • 冒頭で writing-documents への委譲を宣言し、手順 step 1 で invoke する
  • build-readme が持つのは fact allowlist 4種・section composition・canonical section palette・README 固有の落ちる典型・fact の収集経路
  • build-pr-description が持つのは allowlist 5種・Why → What → Test → Notes 骨子・判断の住処・PR 固有の落ちる典型・fact の収集経路
  • 例外は宣言の形になった: build-readme は paragraph を h1 直下の lead のみに許し、nest と理由節を許さない。build-pr-description は Why の nest と Notes の理由節だけを許す
  • 完了チェックは共通項目を落とし、document 型固有の項目だけを持つ
  • session leak の禁止が build-readme にも効く(従来は build-pr-description だけが持っていた)

Test

bun test
  • 40 pass / 0 fail — skill manifest 20 件(writing-documents を含む)と CLI 20 件
  • bun run agent-skills list の inventory に writing-documents が description 付きで現れる

Notes

  • 共有 reference file(skills/_shared/*.md)は却下 — src/cli.ts:233 の destination が target.directory + skill.name で skill directory 単位なので、symlink 経路では skill の外にある共有 file に到達できず plugin 経路だけで有効になる
  • CLAUDE.md の恒久 rule 化は却下 — 「paragraph 禁止」は成果物 document に限る scope が必要で、無条件の rule は会話の応答自体に効いてしまう
  • writing-documents の description は単独 trigger を残した。誤発火のリスクはあるが、「この draft の地の文を落として」型の直接依頼が独立して発生する
  • 既存 evals(build-readmebuild-pr-description)は成果物への assertion だけなので変更なし
  • bun run lint は未実行 — devDependencies 未 install の環境で、TS に変更がないため CI に委ねる

build-readme と build-pr-description が持っていた形式の規律を writing-documents に
1箇所化し、両者は委譲を宣言する。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…d and caller skills

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant