diff --git a/README.md b/README.md index 6390a28..a5db464 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,23 @@ $ brew install chezmoi $ chezmoi init git@github.com:yappiii/dotfiles.git ``` + +## Shared Skills + +This repository now keeps reusable AI skills in a single shared source and distributes them to both Codex and Claude through `chezmoi`. + +- Shared source: `src/.chezmoitemplates/skills/common//` +- Codex target: `src/dot_agents/skills//` +- Claude target: `src/dot_claude/skills//` + +The target-side files are thin `.tmpl` wrappers that `include` the shared source, so the skill body is edited in one place only. + +### Current common skills + +- `japanese-technical-writing` + +### Notes + +- General-purpose skills belong in the shared source and can be shipped to both agents. +- Project-specific skills should stay in the target repository that needs them. +- Imported ideas should be rewritten into original wording and structure unless the upstream license clearly permits verbatim reuse. diff --git a/src/.chezmoitemplates/skills/common/japanese-technical-writing/SKILL.md b/src/.chezmoitemplates/skills/common/japanese-technical-writing/SKILL.md new file mode 100644 index 0000000..886d420 --- /dev/null +++ b/src/.chezmoitemplates/skills/common/japanese-technical-writing/SKILL.md @@ -0,0 +1,36 @@ +--- +name: japanese-technical-writing +description: Use when writing, rewriting, or reviewing Japanese technical documents such as articles, design notes, handbooks, or book chapters, especially when the text needs a clear argument, restrained tone, and low reader load. +--- + +# Japanese Technical Writing + +## Overview + +Use this skill to keep Japanese technical prose precise, readable, and easy to revise. +It favors explicit structure, concrete claims, and calm wording over rhetorical flourish. + +## When to Use + +- Drafting a new Japanese technical article, memo, or chapter +- Rewriting an existing draft that feels verbose or logically loose +- Reviewing prose for structure, tone, and evidence quality + +## How to Work + +1. Identify the reader, their expected background, and the decision or understanding the text should produce. +2. Organize the text paragraph by paragraph so each paragraph has one role: claim, explanation, evidence, procedure, or consequence. +3. Check whether each claim is supported by the right kind of evidence, example, or definition. +4. Remove filler, repeated framing, and decorative transitions that do not change the reader's understanding. + +## Required References + +Read `references/style-guide.md` before substantial writing or rewriting. +Use `references/review-checklist.md` when reviewing or polishing an existing draft. + +## Output Expectations + +- Keep Japanese prose direct and calm. +- Prefer concrete nouns and verbs over abstract phrases. +- Split argument jumps with explicit bridge sentences. +- Demote side remarks to notes, lists, or separate sections when they interrupt the main line. diff --git a/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/review-checklist.md b/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/review-checklist.md new file mode 100644 index 0000000..e6494c5 --- /dev/null +++ b/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/review-checklist.md @@ -0,0 +1,11 @@ +# Review Checklist + +- Is the intended reader clear from the opening section? +- Does each paragraph have one identifiable role? +- Are topic shifts announced before new terms or questions appear? +- Does each major claim have matching evidence, an example, or an explicit rationale? +- Are definitions introduced before the text relies on them? +- Are key terms used consistently instead of being restyled with near-synonyms? +- Are there filler openings, decorative transitions, or repeated summaries that can be cut? +- Would moving any aside into a note, list, or separate section improve the main flow? +- Does the ending leave the reader with a concrete conclusion, decision, or next step? diff --git a/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/style-guide.md b/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/style-guide.md new file mode 100644 index 0000000..82ab515 --- /dev/null +++ b/src/.chezmoitemplates/skills/common/japanese-technical-writing/references/style-guide.md @@ -0,0 +1,53 @@ +# Style Guide + +## Goal + +Write Japanese technical prose that helps the reader understand, judge, or act. +Every sentence should either advance the argument, explain a mechanism, or support a decision. + +## Formatting + +- Use one sentence per line. +- Separate paragraphs with a blank line. +- Put code, logs, commands, diffs, and configuration fragments in fenced code blocks. +- Use lists for definitions, conditions, procedures, and comparisons when structure matters more than prose rhythm. +- Reserve emphasis for true first-time definitions or important warnings. + +## Paragraph Design + +- Give each paragraph one job. +- Start the paragraph with the topic or claim it will develop. +- Continue with explanation, evidence, or consequence in that order when possible. +- Start a new paragraph when the text changes subject, question, or level of abstraction. +- Add a short bridge sentence when a paragraph depends on the conclusion of the previous one. + +## Argument Quality + +- State claims in a falsifiable way. +- Match the evidence to the claim type. +- Define terms before depending on them. +- Prefer one precise term consistently instead of rotating synonyms for style. +- If a cited theory, definition, or paper does not affect the next judgment, cut it. + +## Reader Load + +- Prefer short, explicit sentences over compressed abstraction. +- Remove openings that only announce intent, such as "ここでは説明します" when the next sentence already does it. +- Replace vague references like "これ" or "そのようなもの" when the referent is not obvious. +- Move side remarks, historical notes, and optional nuance out of the main path when they slow the core explanation. + +## Tone + +- Keep the tone calm, concrete, and non-performative. +- Avoid exaggerated praise, dramatic contrast, and motivational filler. +- Prefer "なぜそうなるか" and "どう使い分けるか" over theatrical phrasing. +- Avoid sounding machine-generated by cutting stock transitions and over-general summaries. + +## Revision Pass + +Check the draft in this order: + +1. Purpose: does the draft clearly change the reader's understanding or decision? +2. Structure: does each paragraph have one role and connect to the next? +3. Evidence: is each important claim supported by the right explanation, example, or reference? +4. Language: can any sentence be made shorter, more concrete, or less repetitive? diff --git a/src/dot_agents/skills/japanese-technical-writing/SKILL.md.tmpl b/src/dot_agents/skills/japanese-technical-writing/SKILL.md.tmpl new file mode 100644 index 0000000..942bceb --- /dev/null +++ b/src/dot_agents/skills/japanese-technical-writing/SKILL.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "SKILL.md") }} diff --git a/src/dot_agents/skills/japanese-technical-writing/references/review-checklist.md.tmpl b/src/dot_agents/skills/japanese-technical-writing/references/review-checklist.md.tmpl new file mode 100644 index 0000000..e67abf7 --- /dev/null +++ b/src/dot_agents/skills/japanese-technical-writing/references/review-checklist.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "references" "review-checklist.md") }} diff --git a/src/dot_agents/skills/japanese-technical-writing/references/style-guide.md.tmpl b/src/dot_agents/skills/japanese-technical-writing/references/style-guide.md.tmpl new file mode 100644 index 0000000..1156afb --- /dev/null +++ b/src/dot_agents/skills/japanese-technical-writing/references/style-guide.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "references" "style-guide.md") }} diff --git a/src/dot_claude/skills/japanese-technical-writing/SKILL.md.tmpl b/src/dot_claude/skills/japanese-technical-writing/SKILL.md.tmpl new file mode 100644 index 0000000..942bceb --- /dev/null +++ b/src/dot_claude/skills/japanese-technical-writing/SKILL.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "SKILL.md") }} diff --git a/src/dot_claude/skills/japanese-technical-writing/references/review-checklist.md.tmpl b/src/dot_claude/skills/japanese-technical-writing/references/review-checklist.md.tmpl new file mode 100644 index 0000000..e67abf7 --- /dev/null +++ b/src/dot_claude/skills/japanese-technical-writing/references/review-checklist.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "references" "review-checklist.md") }} diff --git a/src/dot_claude/skills/japanese-technical-writing/references/style-guide.md.tmpl b/src/dot_claude/skills/japanese-technical-writing/references/style-guide.md.tmpl new file mode 100644 index 0000000..1156afb --- /dev/null +++ b/src/dot_claude/skills/japanese-technical-writing/references/style-guide.md.tmpl @@ -0,0 +1 @@ +{{ include (joinPath .chezmoi.sourceDir ".chezmoitemplates" "skills" "common" "japanese-technical-writing" "references" "style-guide.md") }}