otnc/skills_japanese-style / skills/japanese-style
japanese-style
Verified日本語の回答、進捗報告、手順、要約、ドキュメント、コードコメント、コミットメッセージや PR の説明を書く・直すときに、文章の構成、文体、用語、表記を整える。「日本語で答えて」「日本語でまとめて」「日本語を校正して」などの依頼や、読点「、」の打ちすぎ・位置、曖昧な主語、翻訳調、図表の説明、不自然な漢字訳、文字化けを確認するときに使う。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.1 KB |
| references/commas.md | markdown | 10.1 KB |
| references/kangxi-radicals.md | markdown | 10.1 KB |
| references/terminology.md | markdown | 7.8 KB |
| references/writing-examples.md | markdown | 3.7 KB |
| references/writing-guide.md | markdown | 7.9 KB |
| scripts/lint.js | script | 7.1 KB |
| scripts/package.json | manifest | 23 B |
SKILL.md
View on GitHub---
name: japanese-style
description: 日本語の回答、進捗報告、手順、要約、ドキュメント、コードコメント、コミットメッセージや PR の説明を書く・直すときに、文章の構成、文体、用語、表記を整える。「日本語で答えて」「日本語でまとめて」「日本語を校正して」などの依頼や、読点「、」の打ちすぎ・位置、曖昧な主語、翻訳調、図表の説明、不自然な漢字訳、文字化けを確認するときに使う。
license: MIT
---
# 日本語の文章
日本語で書く部分は、読み手や媒体に合わせて、意味をすぐに取れる文章にする。英語のコードやログを読んだあとも、日本語の指定がある進捗、レビュー、結論は日本語で書く。引用するログ、コマンド、識別子は元の表記を保つ。
## 文体と表記
- 会話では相手との距離に合う口調を使う。ドキュメントやコメントを編集するときは、周囲の文体と表記に合わせる。対外文書は相手との関係に合う敬語を使う。
- 地の文の句読点は、指定や既存の表記規則がなければ「、」「。」を使う。数字、括弧、送り仮名、用語の表記は、同じ文章の中で意味や用途が同じならそろえる。改行は段落や項目の切れ目に置く。
- 読点は、長い条件節や並列する項目の境目、係り先が紛らわしい位置に打つ。直後の語にかかる短い修飾語はつなげて書く。一文に複数の読点があれば、大きな区切りを見つけてから、その前後で省ける読点や文を分けられる箇所を探す。[読点の使い方と修正例](references/commas.md)
- 質問への回答や作業報告は、答えや結果から書く。読者の判断や操作が変わる条件は、その近くに添える。手順や並列する項目にはリストを使い、原因と結果のつながりは文で示す。
- 説明を続けるときは、質問や前の文に出た内容を足がかりにして情報を足す。読み手が知らない用語は役割と一緒に紹介し、同じ用語を次の文で受ける。
- 動作主や修飾先が複数に読めるときは、語順を整え、必要なら主語を補う。動作主が途中で変わる場合は、文を分けると関係が追いやすい。コードやツールが実際に処理するなら、その名前を主語にしてよい。
- 「設定が効く」「表示が壊れる」のような言い回しで具体的な変化が伝わらないときは、対象、条件、観測できた結果を書く。根拠から特定できる範囲で具体化する。
- 要約や推敲では、元の数値、条件、確かさを保つ。未確認の事項が読み手の判断に関わる場合は、確認済みの範囲を明示する。PR の説明や運用ドキュメントに残す場合は、未確認の対象と確認方法が後から読んでも分かるように書く。
- 補足が長いときは文を分ける。強調は項目名や画面のラベルを見つけやすくするために使い、コードやコマンドはコード表記で示す。
[文章の組み立てと表記のガイド](references/writing-guide.md) には、回答の情報量、条件や数値の示し方、Markdown、図表と数式、あとから読まれる文章のルールがある。文体や直し方を例で確かめるときは、[会話・ドキュメント・コメント・要約の修正例](references/writing-examples.md) を見る。
## 用語の決め方
1. ユーザーが指定した表記や、対象プロジェクトの用語集・既存ドキュメントに従う。画面のラベル、正式名称、直接引用、コマンド、API の識別子は元の表記を保つ。
2. 表記の指定がない場合は、読み手がその対象を会話や検索で何と呼ぶかを考える。ユーザーの言い方、周囲の文章、製品やライブラリのドキュメントが手がかりになる。略語や英字表記が定着している場合は、`PR` や `HTTP` のようにそのまま使える。
3. 「日本語で」と指定されても、分野で定着しているカタカナ語は、用語例に載っていないものも含めて使う。カタカナ語のほうがすぐに通じるなら、和語や漢字の熟語への置き換えは不要。既存の文に直訳があれば、何を指すか確かめてから普段使われる表記に戻す。
4. 読み手に通じる日常語も使う。たとえば一般向けの案内なら「設定を更新する」、書籍なら「第2版」が自然。初めて出てくる専門用語を読み手が画面やドキュメントで探す必要があるなら、その用語を残して初出時に短く説明する。
## 用語と文字のチェック
迷ったときや、既存の技術文書に直訳が続くときは、[技術用語の例](references/terminology.md) を見る。各行は使い分けの例で、対象や操作を確かめてから適用する。
送信前に、見出し、箇条書き、結論で用語が変わっていないか確認する。同じ対象には同じ呼び方を使い、「前の版へ戻した」のような短いまとめでも、ソフトウェアの話なら「前のバージョンに戻した」と書く。
Node.js が使えるなら、新規・編集した日本語の文章を [lint.js](scripts/lint.js) で確認できる。技術用語は `--terminology`、部首記号は `--kangxi-radicals`、文字化けは `--encoding` を選ぶ。複数のオプションを指定できる。省略すると全項目を調べる。
以下はスキルのディレクトリから UTF-8 のファイルを調べる例。会話やメッセージの下書きを標準入力から渡すときは、ファイル名の代わりに `-` を指定する。
```sh
node scripts/lint.js --terminology article.md
node scripts/lint.js --kangxi-radicals article.md
node scripts/lint.js --encoding article.md
```
- `warn [terminology]` はカタカナ語にできるかを確かめる候補。使い分けが適切な語や意図的な表記は残す。用語例にないカタカナ語にも「用語の決め方」を適用する。
- `error [kangxi-radical]` は部首記号が見つかった箇所。普通の文章に紛れ込んでいたら文脈に合う漢字に直す。部首の説明や直接引用で意図的に使う場合はその文字を保つ。[康熙部首214字の対応表](references/kangxi-radicals.md)
- `error [encoding]` は不正な UTF-8 のバイト列か、入力に含まれる置換文字(U+FFFD)。不正なバイト列なら、元の文字コードを確かめて読み直す。置換文字が意図せず入っていたら原文と照合して直す。引用や説明で意図して使った置換文字は保つ。
見た目が同じなのに検索や置換が一致しないときは、元の文字列を取り出してコードポイントを確かめる。置換対象には元ファイルの文字列を使い、修正が必要な箇所に絞って直す。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |