skill-maintenance

Skill Maintenance Workflow

Subagent連携の原則

SkillとSubagentの関係:

• Subagentのフロントマターに skills: skill1, skill2 と記載
• そのSubagentが呼び出されると、指定Skillsは全てSubagent内で実行される
• Skillは単独実行も可能だが、Subagent経由ならコンテキスト分離で並列処理等が可能

Subagentを作るべきSkill:

• 並列処理、WEB検索、アイデア出し、仮説立て等、コンテキスト非依存で価値があるもの
• 作成時は subagent-maintenance ワークフローを使用

Subagent不要なSkill:

• 単なる評価軸チェック用のためだけの個別 qa-xxx は原則作成しない（QCは共通Subagent qa-skill-qc を使用）

Instructions

1. Preflight:

   • ドキュメント精査原則（Preflight必須）：テンプレート確認後、生成前に必ず以下を実施すること。
     • アジェンダ・依頼文に記載された参照資料を全て読み込む。
     • Flow/Stock配下の関連資料（前回議事録・要望リスト・プロジェクトREADME等）を網羅的に検索・確認する。
     • 確認できなかった資料は「未参照一覧」として成果物に明記する。
     • これらを完了するまで生成を開始しない。
   • 変更対象（operation=edit/add）、対象Skillファイル、変更範囲、期待成果、理由、検証手順を確認する（推測しない）。
   • 既存Skillを読み、必須セクション/テンプレート構造を把握する（テンプレートファースト）。
   • ./assets/skill_skeleton_template.md を参照する。

2. 生成:

   • ./questions/skill_maintenance_questions.md に従い入力を確定し、最小差分で修正する。
   • operation=edit（既存Skillの保守）では、特別な指示がない限り既存の機能/挙動/情報に干渉せず、フォーマット（型）整形に限定する（削除/無効化はユーザー明示指示時のみ）。
   • 既存機能・ロジック・定義を欠損させない。
   • Skillの必須セクション区切りを崩さない。

3. Skill新規作成時のアセット設置:

   • 新規Skill作成時は以下のフォルダ構造を作成すること:

     {{AGENT_CONFIG_DIR}}/skills/{skill-name}/
     ├── SKILL.md                    # 必須: Skill定義
     ├── assets/                     # 必須: テンプレート
     │   └── {name}_template.md
     ├── questions/                  # 必須: 質問リスト
     │   └── {name}_questions.md
     ├── evaluation/                 # 必須: 評価指標
     │   └── evaluation_criteria.md
     ├── triggers/                   # 必須: WF連携の起動条件
     │   └── next_action_triggers.md
     └── scripts/                    # 任意: 検証/自動化スクリプト
         └── {script_name}.py
     

   • {{AGENT_CONFIG_DIR}} は実行環境に応じて決定:
     • Cursor: .cursor
     • Claude Code: .claude
     • Codex: .codex
   • evaluationフォルダは以下の構成とする:
     • evaluation_guide.md: 評価レベル定義（Most/More/Good）・採点基準・QC報告フォーマット・観点別ファイル一覧
     • 観点別ファイル（標準仕様）:
       • Most（Pass/Fail判定）: {observation}_most.md（例: structure_most.md, ai_detection_most.md）
       • More（スコアリング）: {observation}_more.md（例: human_likeness_more.md）
     • レガシー（観点が少ないSkill向け）: most_criteria.md, more_criteria.md
   • 観点別並列実行が標準: QC実行時、qa-skill-qcが観点数だけ並列実行される
   • evaluation_guide.md に観点別ファイル一覧を明記し、どの観点で並列実行するかを定義する
   • SKILL.md の Resources セクションに全アセットを明記する。

4. Subagentとして独立実行されるSkillの場合:

   • ## Subagent Execution セクションをSKILL.md末尾に追加し、以下を明記する:
     • サブエージェント: 対応するagents/*.mdのパス
     • 用途: 並列処理、バックグラウンド実行等の具体的用途
     • 入力: 期待されるパラメータ
     • 出力: 処理結果の形式
   • 対応するSubagentの skills: フィールドにこのSkill名を追加する

5. triggers/next_action_triggers.md の作成（必須）:

   • 新規Skill作成時は必ずtriggers/next_action_triggers.mdを作成する。
   • ./assets/next_action_triggers_spec.md の仕様に従って起動条件を定義する。
   • 起動条件は検証可能な形式で記載する（曖昧表現NG）:
     • NG: 「〜が必要なら」「〜したい場合」
     • OK: 「成果物に〜セクションが存在する」「〜が未作成（ファイル不存在）」
   • SKILL.mdのResourcesセクションに- triggers: ./triggers/next_action_triggers.mdを追加する。
   • SKILL.mdのNext Actionセクションを以下の形式に更新する:

     ## Next Action
     - triggers: ./triggers/next_action_triggers.md
     
     起動条件に従い、条件を満たすSkillを自動実行する。
     

6. CLAUDE.md / AGENTS.md への追記:

   • 新規Skill作成時は以下を確認・追記すること:
     • ワークフロー索引: 該当フェーズ（Initiating/Planning/Executing等）に追記
     • パス辞書: 必要なパスパターンがあれば patterns: セクションに追記
   • 追記フォーマット:

     # ワークフロー索引の例（CLAUDE.md Section 6）
     ### Executing（実行）
     new-workflow-name → next-workflow-name
     
     # パス辞書の例（CLAUDE.md Section 7 patterns:）
     new_template:    "{{patterns.flow_date}}/new_template.md"
     

   • 追記後、python3 scripts/update_agent_master.py --source cursor --force で3環境同期を実施する。

7. 検証:

   • 必要に応じて ./assets/skill_check_report_template.md 形式で検証ログを作成する。

8. QC（必須）:

   • 共通QC Subagent（qa-skill-qc）に評価・チェックを委譲する。
   • qa-skill-qc は以下を順にReadし、評価を実施する:
     1. ./evaluation/evaluation_guide.md（評価レベル定義・採点基準・QC報告フォーマット）
     2. ./evaluation/most_criteria.md（必須修正項目チェック）
     3. ./evaluation/more_criteria.md（推奨修正項目スコアリング）
   • 以下の観点を中心にQCを実施する:
     • 必須セクション維持
     • 機能欠損がないか
     • 差分最小
     • 検証手順の不足
     • triggers/next_action_triggers.md が作成されているか
     • 起動条件が検証可能な形式か
     • Most項目: Pass/Fail判定、未修正時はFail
     • More項目: スコアリング（100点満点）、80点以上Pass
   • QC報告フォーマットに従い評価結果を記録:

     ### QC結果: [Pass/Conditional Pass/Fail]
     
     #### Most（必須修正）
     - [x] 項目名: Pass
     - [ ] 項目名: Fail → 修正必須
     
     #### More（推奨修正）
     スコア: [XX]/100
     
     #### 指摘事項
     1. [Most/More] [項目名]: [指摘内容]
     

   • 評価結果を成果物末尾に追記する（修正有無/理由）。
   • 重大な問題がある場合は修正し、再度 qa-skill-qc でQCする（最大3回）。

9. バックログ反映:

   • 次アクション（3環境同期、レビュー依頼、ロールバック準備等）を抽出しバックログへ反映する。
   • 反映先・編集制約・差分提示は AGENTS.md / CLAUDE.md の全体ルールに従う。

subagent_policy:

• 単なる評価目的のためだけの個別 qa-xxx サブエージェントは Agents/ に作成しない
• QCは共通Subagent qa-skill-qc を使用し、各Skillの ./evaluation/evaluation_guide.md, ./evaluation/most_criteria.md, ./evaluation/more_criteria.md に基づいて評価する
• Subagentが必要なSkillは subagent-maintenance で作成し、skills: フィールドで連携

Resources

• questions: ./questions/skill_maintenance_questions.md
• questions: ./questions/path_update_questions.md
• questions: ./questions/skill_check_questions.md
• assets: ./assets/skill_skeleton_template.md
• assets: ./assets/questions_markdown_template.md
• assets: ./assets/skill_maintenance_log_template.md
• assets: ./assets/skill_check_report_template.md
• assets: ./assets/skills_official_alignment_conversion.md
• assets: ./assets/next_action_triggers_spec.md
• evaluation: ./evaluation/evaluation_guide.md
• evaluation: ./evaluation/most_criteria.md
• evaluation: ./evaluation/more_criteria.md
• triggers: ./triggers/next_action_triggers.md
• scripts: ./scripts/update_agent_master.py
• scripts: ./scripts/lint_skills.py

Next Action

• triggers: ./triggers/next_action_triggers.md

起動条件に従い、条件を満たすSkillを自動実行する。