agentsclimarketplace
Sign in

Documentation writing

Skill redamoon/skills/skills/documentation-writing

プロジェクトの技術ドキュメント（README、手順書、設計メモ、API 説明など）を執筆・推敲する際のガイドライン。読者・目的に合わせた構成、日本語の明確さ、AIっぽい表現の排除を重視する。From its SKILL.md

Install
npx -y skills add redamoon/skills --skill documentation-writing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

6.1 KB, ~2.2k tokens by cl100k_base, as published. Nobody here has run it

技術ドキュメント執筆スキル

プロジェクト内の Markdown ドキュメントを、読者が目的を達成できる形で書く・直すためのガイドです。ブログ記事向けのプラットフォーム記法（Zenn / はてな / note）ではなく、リポジトリやプロダクトの説明・運用・開発向け文書を対象とします。

When to Use

  • README、CONTRIBUTING、CHANGELOG などリポジトリ文書を書く・更新するとき
  • セットアップ手順、運用手順、トラブルシューティングを Markdown でまとめるとき
  • API・モジュール・アーキテクチャの説明ドキュメントを新規作成・推敲するとき
  • ADR（Architecture Decision Record）や設計メモを整理するとき
  • 既存ドキュメントの構成見直しや「読みにくいので直して」と依頼されたとき
  • ドキュメントのレビュー・品質チェックを行うとき

ブログ記事の執筆・投稿向けには、同リポジトリの zenn-blog-writing や blog-workflow を使う。

Instructions

執筆の前提

  1. 読者を決める: 新規参加者 / 日常開発者 / 運用担当 / 利用者 — 誰向けかで深さと用語を変える
  2. 目的を1文で決める: 読後に読者が何ができるようになるか（例: ローカルで起動できる、障害時にログを確認できる）
  3. 既存ドキュメントを確認する: 重複セクションを増やさず、リンクでつなぐ
  4. 事実と推測を分ける: 未確認の挙動は「想定」「要確認」と明記する

文書タイプ別の推奨構成

README（リポジトリの顔）

  1. 何のプロジェクトか（1〜2文）
  2. 主な機能・用途
  3. 必要条件（ランタイム、ツール）
  4. クイックスタート（最短で動かす手順）
  5. 詳細ドキュメントへのリンク
  6. ライセンス

手順書（How-to）

  1. 目的と完了条件
  2. 前提（権限、環境、依存）
  3. 手順（番号付き、1ステップ1アクション）
  4. 確認方法（期待する出力・画面）
  5. よくある失敗と対処

リファレンス（API・設定・コマンド）

  • 項目ごとに同じテンプレート（名前、説明、型・引数、例、注意）
  • 表または見出しでスキャンしやすくする
  • 例はコピーしてそのまま使える形にする

ADR / 設計メモ

  • Context: 背景・課題
  • Decision: 採用した方針
  • Consequences: メリット・デメリット・トレードオフ
  • Status: 提案中 / 承認済み / 廃止 — と日付

文体と日本語

  • 本文は ですます調 を基本とする
  • 1文は60文字前後を目安にし、長い文は分割する
  • 文末は「。」で終える（「：」で終えない）
  • 専門用語は初出で短く説明する。略語は正式名称を併記する
  • 受動態より能動態を優先する（「〜されます」→「〜します」）
  • 箇条書きで情報を整理し、段落は1トピックに絞る

マークダウンの書き方

  • 見出しは論理的な階層（# は文書タイトル1つのみ、本文は ## から）
  • 見出し内の太字は避ける
  • ファイル名・コマンド・API パス・環境変数は インラインコード（バッククォート）で書く。太字と併用しない
  • コードブロックには言語を指定する（bash, typescript, json など）
  • リンクテキストは具体的にする（「こちら」だけにしない）
  • スクリーンショットを使う場合は、何が写っているかキャプションで補足する

AIっぽい文章の排除

以下は技術ドキュメントでも避ける。

避ける代替
「重要:」「注意:」などの機械的プレフィックス見出しや通常文で述べる
「革命的」「完璧な」などの誇張事実・数値・条件で述べる
ダッシュ区切り（—— / —）で文をつなぐ文を分ける、括弧、「つまり」
同じ言い回しの繰り返し具体例・手順・表で置き換える
冗長な前置き（「本ドキュメントでは〜」の連発）目的が分かれば省略

品質チェックに textlint を使うプロジェクトでは、編集後に textlint-blog スキル（またはプロジェクトの textlint 設定）で Markdown を検証する。

コード例の品質

  • 動作確認済み、または「要確認」と明記する
  • バージョン・OS・ツールの前提を書く
  • プレースホルダは <YOUR_VALUE> のように統一する
  • シークレットや個人情報を例に含めない

レビュー時のチェックリスト

内容

  • 読者と目的に合っているか
  • 手順どおりに再現できるか（コマンド・パス・権限）
  • 古い情報（廃止 API、削除済み機能）が残っていないか
  • 他ドキュメントと矛盾していないか

文章

  • ですます調で統一されているか
  • AIっぽい定型句やダッシュ区切りがないか
  • 専門用語に初出説明があるか
  • textlint を使う場合、エラーが解消されているか

構成

  • 見出し階層が飛び級になっていないか
  • 目次やリンクで長文を辿りやすいか
  • 重複セクションを統合できるか

出力の進め方

  1. 不足情報があれば、読者・環境・完了条件を短く確認する
  2. 既存ファイルを読み、追記か新規かを判断する
  3. 構成案（見出し一覧）を示してから本文を書く（大きな変更のとき）
  4. 変更点を箇条書きで要約する（何を追加・削除・移動したか）

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most docs writing skills give in ~2.2k tokens

Counted across 1,637 of the 3,044 authors here whose files we hold, read 2026-08-07

  • Announce the skill at startin 54 of 1637, across 26 files
  • Convert legacy doc files before editingin 45 of 1637, across 7 files
  • Predict questions readers might askin 42 of 1637, across 4 files
  • Generate clarifying questions for initial contextin 42 of 1637, across 3 files
  • Create document scaffold with placeholder textin 42 of 1637, across 3 files
  • Brainstorm content options for each sectionin 42 of 1637, across 3 files
  • Test the document with a fresh context-less instancein 42 of 1637, across 3 files
  • Include exact file paths in every taskin 42 of 1637, across 15 files
  • Ask interview questions one at a timein 42 of 1637, across 27 files
  • Apply surgical edits during refinementin 41 of 1637, across 2 files
  • Offer structured workflow or freeformin 40 of 1637, across 1 file
  • Ask for document meta-contextin 40 of 1637, across 2 files

Said here and by no other author read

  • define the reader before writing
  • use polite Japanese style
  • keep sentences around 60 characters
  • use inline code for technical terms
  • use placeholders consistently in examples
  • show structure before writing body text

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 326,851. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.