create-ai-project 1.16.0 → 1.16.2

package/docs/guides/en/quickstart.md

@@ -84,6 +84,24 @@ The workflow is: create design documents, review them with users to align unders
 
 For detailed mechanics, see [this article](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b).
 
+## What's Next?
+
+Now that you're set up, here are common things you'll want to do and how to do them.
+
+| "I want to..." | How |
+|---|---|
+| Have AI reference my library docs (llms.txt, API refs, etc.) | Add to an existing skill or [create a new one](./skills-editing-guide.md) — [see below](#example-where-to-put-library-documentation) |
+| Enforce my team's coding conventions | Use `/create-skill` or [create a custom skill manually](./skills-editing-guide.md) |
+| Set project-specific constraints and context | Run `/project-inject` |
+| Learn the full set of available commands | [Use Cases & Commands](./use-cases.md) |
+| Customize how agents behave | Edit skill files under `.claude/skills/` |
+
+Skills are the primary way to give AI project-specific knowledge. See the [Skills Editing Guide](./skills-editing-guide.md) for how to create your own.
+
+### Example: Where to Put Library Documentation
+
+Where to place library docs depends on your project — there's no single right answer. Think about **when AI needs the information** and **what it relates to**: add to an existing skill, a phase-specific doc, or create a dedicated skill. See the [Use Cases guide](./use-cases.md#want-ai-to-reference-specific-library-docs) for concrete examples and the [Skills Editing Guide](./skills-editing-guide.md#determining-where-to-document) for details.
+
 ## Troubleshooting
 
 If things aren't working, check the following.

package/docs/guides/en/skills-editing-guide.md

@@ -61,13 +61,61 @@ description: Start with a verb. Use when: specify trigger conditions.
 # Skill content
 ```
 
+### Naming Conventions
+
+Use consistent naming patterns. The [official recommendation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) suggests **gerund form** (verb + -ing) for clarity.
+
+- **Gerund form (recommended)**: `processing-pdfs`, `managing-databases`, `testing-code`
+- **Action-oriented (acceptable)**: `process-pdfs`, `analyze-spreadsheets`
+- **Avoid vague names**: `helper`, `utils`, `tools`, `documents`
+
+**Constraints**: lowercase letters, numbers, and hyphens only. Maximum 64 characters. Cannot contain "anthropic" or "claude".
+
 ### Writing Effective Descriptions
 
-The description is the most critical field — it determines skill selection accuracy.
+The description is the most critical field — it determines skill selection accuracy. At startup, only metadata (name and description) from all skills is loaded. Claude uses descriptions to decide which skill to activate from potentially 100+ available skills. [Research indicates](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) that well-optimized descriptions can improve activation rates from 20% to over 90%.
+
+**Rules**:
 
-1. **Start with a verb**: "Applies TDD process and inspects quality" not "Testing principles"
-2. **Use "Use when:" with concrete triggers**: 3-5 triggers using expressions users actually say
-3. **Over 200 characters signals a split**: The skill's responsibility may be too broad
+1. **Write in third person**: The description is injected into the system prompt. Inconsistent point-of-view causes discovery problems.
+   - Good: "Processes Excel files and generates reports"
+   - Avoid: "I can help you process Excel files"
+   - Avoid: "You can use this to process Excel files"
+2. **Start with a verb**: "Applies TDD process and inspects quality" not "Testing principles"
+3. **Use "Use when:" with concrete triggers**: 3-5 triggers using expressions users actually say
+4. **Be specific and include key terms**: Include both what the skill does and when to use it
+5. **Over 200 characters signals a split**: The skill's responsibility may be too broad
+
+**Constraints**: Maximum 1024 characters. Cannot contain XML tags.
+
+**Good examples**:
+```yaml
+# Specific, verb-first, with triggers
+description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+
+description: Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+**Bad examples**:
+```yaml
+# Too vague — Claude can't determine when to activate
+description: Helps with documents
+description: Processes data
+description: Does stuff with files
+```
+
+### Keep File References One Level Deep
+
+Claude may partially read files when they're referenced from other referenced files. Keep all references directly from SKILL.md to ensure complete reads.
+
+```markdown
+# Good: One level deep from SKILL.md
+See [reference.md](reference.md) for API details
+See [examples.md](examples.md) for usage patterns
+
+# Bad: Nested references
+# SKILL.md → advanced.md → details.md (Claude may not fully read details.md)
+```
 
 ### Progressive Disclosure
 
@@ -96,7 +144,7 @@ This mechanism maintains token efficiency even with many skills defined. Referen
 ## 9 Principles for Maximizing LLM Execution Accuracy
 
 Here are 9 skill creation principles based on LLM characteristics and this boilerplate's design philosophy.
-While we provide a `/refine-skill` command to assist with skill modifications, we ultimately recommend interactive editing through dialogue, as LLMs tend to have difficulty reaching issues without comparing output with thinking after generation.
+We provide `/create-skill` for creating new skills through interactive dialog, and `/refine-skill` for modifying existing skills with quality review. We ultimately recommend interactive editing through dialogue, as LLMs tend to have difficulty reaching issues without comparing output with thinking after generation.
 
 ### 1. Achieve Maximum Accuracy with Minimum Description (Context Pressure vs. Execution Accuracy)
 

package/docs/guides/en/use-cases.md

@@ -114,6 +114,32 @@ Fixes are created as task files under `docs/plans/tasks` and executed by sub-age
 /sync-skills      # Sync skill metadata
 ```
 
+## Want AI to reference specific library docs?
+
+Where to place library docs (like `llms.txt` URLs) depends on your project. Think about **when AI needs the information** and **what it relates to**:
+
+- If a related skill already exists (e.g., a frontend skill covering React), **add the URL there** to keep context together
+- If only needed during a specific phase (e.g., design), **add to that phase's skill or Design Doc**
+- If used broadly across the project, **create a dedicated skill** via `/create-skill` or manually (e.g., `.claude/skills/my-library-docs/SKILL.md`)
+
+After adding or creating a skill, run `/sync-skills` to register it. See the [Skills Editing Guide](./skills-editing-guide.md) for details on [where to document what](./skills-editing-guide.md#determining-where-to-document).
+
+## Want to add team-specific rules?
+
+Use `/create-skill` to create a custom skill through interactive dialog:
+
+```bash
+/create-skill team coding conventions and naming rules
+```
+
+Or create one manually:
+
+1. Create `.claude/skills/my-team-rules/SKILL.md`
+2. Define your coding standards, naming conventions, architectural constraints, etc.
+3. Run `/sync-skills` to register the new skill
+
+Any information you want AI to know about your project can be added as a skill.
+
 ---
 
 # Command Reference
@@ -216,11 +242,11 @@ Use when not adopting the full design-to-implementation process via `/implement`
 **Args**: What to change
 **Process**:
 1. Select skill file
-2. Create change proposal
-3. 3-pass review process
-4. Apply
+2. Create change proposal against skill-optimization editing principles
+3. Quality review by skill-reviewer agent (grade A/B to proceed)
+4. Apply after user approval
 
-Assists with skill file editing. Since skills must be optimized for LLMs to maintain execution accuracy, creating optimal skills with this command alone is difficult. Refer to the [Skills Editing Guide](./skills-editing-guide.md) and refine skills through command usage or direct dialogue with LLMs.
+Assists with skill file editing. Uses the skill-reviewer agent for quality evaluation. Since skills must be optimized for LLMs to maintain execution accuracy, creating optimal skills with this command alone is difficult. Refer to the [Skills Editing Guide](./skills-editing-guide.md) and refine skills through command usage or direct dialogue with LLMs.
 
 ### /sync-skills
 **Purpose**: Sync skill metadata

package/docs/guides/ja/quickstart.md

@@ -85,6 +85,24 @@ AI活用によるスループットを最大化するためには、極力人間
 
 詳しい仕組みについては、[こちらの記事](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)で解説されています。興味があれば読んでみてください。
 
+## 次のステップ
+
+セットアップが完了したら、よくあるカスタマイズのやり方を確認しておきましょう。
+
+| やりたいこと | 方法 |
+|---|---|
+| AIにライブラリのドキュメント（llms.txt、APIリファレンス等）を参照させたい | 既存スキルに追記するか、[新規作成](./skills-editing-guide.md) — [判断例はこちら](#例ライブラリドキュメントの置き場所) |
+| チームのコーディング規約をAIに守らせたい | `/create-skill`を使うか、[手動でカスタムスキルを作成](./skills-editing-guide.md) |
+| プロジェクト固有の制約やコンテキストを設定したい | `/project-inject`を実行 |
+| 利用可能なコマンドの全体像を知りたい | [ユースケース＆コマンド](./use-cases.md) |
+| エージェントの振る舞いをカスタマイズしたい | `.claude/skills/`配下のスキルファイルを編集 |
+
+プロジェクト固有の知識をAIに伝えるにはスキルが一番手軽です。作り方は[スキル編集ガイド](./skills-editing-guide.md)を参照してください。
+
+### 例：ライブラリドキュメントの置き場所
+
+ライブラリのドキュメント（`llms.txt`のURL等）をどこに置くかは、プロジェクトでの使われ方によって変わります。**AIがいつその情報を必要とするか**と**何と関連が深いか**で判断してください。既存スキルへの追記、フェーズ固有のドキュメントへの記載、専用スキルの作成など、いくつかのパターンがあります。具体的な判断例は[ユースケースガイド](./use-cases.md#aiにライブラリのドキュメントを参照させたいときは)に、詳しい判断基準は[スキル編集ガイド](./skills-editing-guide.md#どのファイルに記載するべきかの判断基準)にまとめています。
+
 ## トラブルシューティング
 
 うまくいかないときは、以下を確認してください。

package/docs/guides/ja/skills-editing-guide.md

@@ -61,13 +61,61 @@ description: 動詞で開始する説明文。Use when: トリガー条件を明
 # スキル本文
 ```
 
+### 命名規則
+
+一貫した命名パターンを使用する。[公式の推奨](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)は**動名詞形**（verb + -ing）。
+
+- **動名詞形（推奨）**: `processing-pdfs`, `managing-databases`, `testing-code`
+- **動作形（許容）**: `process-pdfs`, `analyze-spreadsheets`
+- **曖昧な名前は避ける**: `helper`, `utils`, `tools`, `documents`
+
+**制約**: 小文字・数字・ハイフンのみ。最大64文字。"anthropic"や"claude"は使用不可。
+
 ### descriptionの書き方
 
-descriptionはスキル選択の精度を左右する最重要フィールド。
+descriptionはスキル選択の精度を左右する最重要フィールド。起動時に全スキルのメタデータ（name, description）のみが読み込まれ、100以上のスキルから適切なものを選ぶ判断材料になる。[公式のベストプラクティス](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)によると、descriptionを最適化するだけでスキルが正しく選ばれる確率が20%台から90%以上まで上がる。
+
+**ルール**:
 
-1. **動詞で開始する**: 「テストの原則」ではなく「TDDプロセスを適用し品質基準を検査」
-2. **"Use when:"で具体的なトリガーを明示**: ユーザーが実際に使う表現で3-5個に絞る
-3. **200文字を超えたら分割を検討**: 責務が広すぎるシグナル
+1. **三人称で書く**: descriptionはシステムプロンプトに埋め込まれる。視点がブレると正しく選ばれにくくなる。
+   - Good: "Processes Excel files and generates reports"
+   - Avoid: "I can help you process Excel files"
+   - Avoid: "You can use this to process Excel files"
+2. **動詞で開始する**: 「テストの原則」ではなく「TDDプロセスを適用し品質基準を検査」
+3. **"Use when:"で具体的なトリガーを明示**: ユーザーが実際に使う表現で3-5個に絞る
+4. **具体的でキーワードを含む**: スキルが何をするか、いつ使うかの両方を含める
+5. **200文字を超えたら分割を検討**: 責務が広すぎるシグナル
+
+**制約**: 最大1024文字。XMLタグは使用不可。
+
+**良い例**:
+```yaml
+# 具体的、動詞始まり、トリガー付き
+description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+
+description: Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+**悪い例**:
+```yaml
+# 曖昧すぎる — Claudeがいつ活性化すべきか判断できない
+description: Helps with documents
+description: Processes data
+description: Does stuff with files
+```
+
+### ファイル参照は1階層まで
+
+参照先のファイルからさらに別のファイルを参照している場合、Claudeが部分的にしか読み取れないことがある。SKILL.mdから直接参照する1階層に留める。
+
+```markdown
+# Good: SKILL.mdから1階層
+See [reference.md](reference.md) for API details
+See [examples.md](examples.md) for usage patterns
+
+# Bad: 入れ子の参照
+# SKILL.md → advanced.md → details.md（details.mdが完全に読まれない可能性）
+```
 
 ### Progressive Disclosure（段階的開示）
 
@@ -96,7 +144,7 @@ descriptionはスキル選択の精度を左右する最重要フィールド。
 ## LLMの実行精度を最大化する9つの原則
 
 スキル作成の原則を9つ紹介します。
-`/refine-skill`コマンドも提供していますが、LLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、対話的にスキルを修正することを最終的には推奨します。
+スキル新規作成には`/create-skill`、既存スキルの品質レビュー付き修正には`/refine-skill`コマンドを提供しています。ただしLLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、対話的にスキルを修正することを最終的には推奨します。
 
 ### 1. 最小記述で最大精度を実現する（コンテキスト圧迫 vs 実行精度）
 

package/docs/guides/ja/use-cases.md

@@ -104,6 +104,32 @@ LLMが規模を自動判定して、必要なドキュメントを作成して
 /sync-skills      # スキルメタデータ同期
 ```
 
+## AIにライブラリのドキュメントを参照させたいときは？
+
+ライブラリのドキュメント（`llms.txt`のURL等）の置き場所は、**AIがいつその情報を必要とするか**と**何と関連が深いか**で決めます。
+
+- 関連するスキルが既にある場合（例：frontendスキルにReactの記載がある）→ **そのスキルにURLを追記**して関連情報をまとめる
+- 特定フェーズでしか使わない場合（例：設計時のみ）→ **該当フェーズのスキルやDesign Docに記載**
+- プロジェクト全体で横断的に使う場合 → `/create-skill`または手動で**専用スキルを作成**（例：`.claude/skills/my-library-docs/SKILL.md`）
+
+スキルを追加・作成したら `/sync-skills` で登録してください。判断基準の詳細は[スキル編集ガイド](./skills-editing-guide.md)の[「どのファイルに記載するべきかの判断基準」](./skills-editing-guide.md#どのファイルに記載するべきかの判断基準)を参照してください。
+
+## チーム固有のルールをAIに守らせたいときは？
+
+`/create-skill` を使うと、対話形式でカスタムスキルを作成できます。
+
+```bash
+/create-skill チームのコーディング規約と命名規則
+```
+
+手動で作成する場合:
+
+1. `.claude/skills/my-team-rules/SKILL.md` を作成
+2. コーディング規約、命名規則、アーキテクチャ上の制約などを定義
+3. `/sync-skills` を実行して新しいスキルを登録
+
+AIに知っておいてほしい情報があれば、スキルとして追加できます。
+
 ---
 
 # コマンドリファレンス
@@ -206,11 +232,11 @@ Design Docから作業計画書を作成します。また、実装に必要な
 **引数**: 変更したい内容
 **実行内容**:
 1. スキルファイル選択
-2. 変更設計案作成
-3. 3回見直しプロセス
-4. 適用
+2. skill-optimizationの編集原則に照らして変更設計案を作成
+3. skill-reviewerエージェントによる品質レビュー（グレードA/Bで次へ進行）
+4. ユーザー承認後に適用
 
-スキルファイルの編集を支援します。スキルはLLMに最適化された文章にしなければ実行精度が落ちてしまうため、本コマンドだけで最良のスキルを作成することは困難です。[スキル編集ガイド](./skills-editing-guide.md)を参照し、コマンド活用もしくはLLMと直接対話しながら、スキルの整備を行なってください。
+スキルファイルの編集を支援します。skill-reviewerエージェントによる品質評価を行います。スキルはLLMに最適化された文章にしなければ実行精度が落ちてしまうため、本コマンドだけで最良のスキルを作成することは困難です。[スキル編集ガイド](./skills-editing-guide.md)を参照し、コマンド活用もしくはLLMと直接対話しながら、スキルの整備を行なってください。
 
 ### /sync-skills
 **用途**: スキルメタデータの同期

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "packageManager": "npm@10.8.2",
   "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
   "keywords": [