Contributing to skills

このリポジトリは、Claude Code / OpenAI Codex CLI 向けのエージェントスキルを集めたモノレポです。各スキルは <skill-name>/ 配下に独立して存在し、それぞれ固有の言語・ツールチェーンを持ちます。

リポジトリの構成

<skill-name>/
├── SKILL.md      # 英語版（正）
├── SKILL.ja.md   # 日本語版
├── scripts/      # 実装本体
└── tests/        # そのスキル用のテスト

• cc-trace/ — Nushell フック + Python（uv / ruff / pytest）
• video-frame-reader/ — Python（uv / ruff / pytest）
• ci-monitoring/ — TypeScript（Bun / oxfmt / oxlint）
• cmd-guard/, commit-guard/, task-watch/ — エージェント向けガードスキル

SKILL.md と SKILL.ja.md は機械翻訳の対ではなく、独立した文章として並行編集すること。 一方を直しても他方を単純コピーで追従させない — 両方読んで意味が伝わるかを個別に確認する。

貢献の前に

• 既存の Issue / PR を確認し、重複を避ける。
• コマンド追加・挙動変更・依存追加など、小さな修正を超える変更は、実装前に Issue で方針を相談する。
• 1 PR は 1 つのスキル・1 つの関心事に絞る。無関係なスキルへの手直しや、ついでのリネームを混ぜない。

開発環境のセットアップ

just setup   # lefthook のインストール（pre-commit フックを有効化）

Nushell (nu)、uv、Bun のうち、触るスキルに応じて必要なものをインストールしておくこと。

ブランチ命名

<type>/<kebab-case-description> の形式を使う:

• feat/ — 新機能
• fix/ — バグ修正
• docs/ — ドキュメントのみの変更
• ref/ — リファクタリング
• test/ — テストのみの変更
• chore/ — 依存更新・雑務

コミットメッセージ

先頭に feat: / fix: / ref: / docs: / chore: のいずれかを付け、要約は現在形・命令形で書く。本文は「何をしたか」ではなく「なぜそうしたか」（制約・トレードオフ・発見した事実）を書く — コードを読めば分かることを本文で繰り返さない。

Claude / Codex などのエージェントが実装した場合は、末尾に Co-Authored-By: を付ける（複数行に分けず、各行を個別の -m として渡す）:

git commit -m "fix: reject empty codex_preset before writing config.json" \
  -m "空文字を渡すと config-codex-preset が既定プリセットにフォールバックし、意図しないモデルへ静かに切り替わっていた。" \
  -m "Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>"

1 コミット = 1 論理タスク。バグを複数直した場合や、フォーマッタ整形と実装変更が混ざる場合は分割する。

変更のワークフロー

1. main からブランチを切る。
2. 実装する。
3. 変更したスキルの tests/ にテストを追加・更新する（下記「検証」参照）。
4. コミットする（lefthook の pre-commit がフォーマット・lint・変更範囲のテストを自動実行する — stage_fixed: true のコマンドは自動整形結果をそのままステージに反映する）。
5. main に向けて PR を作成する。

コーディング規約

Nushell（cc-trace/hooks/, video-frame-reader/）

• nufmt --config nufmt.nuon / nu-lint --config nu-lint.toml の警告に従う。
• ホスト分岐（Claude Code / Codex）が絡む関数は、両ホストの契約差を関数直上のコメントで説明する — 呼び出し側からは意図が読めないため。

Python（cc-trace/scripts/, video-frame-reader/scripts/）

• ruff format / ruff check --fix を通す（設定は各スキルの pyproject.toml）。
• uv run --with pytest python -m pytest tests/ -q がグリーンであること。

TypeScript（ci-monitoring/packages/）

• bun run fmt / bun run lint / bun run typecheck を通す。
• CI（.github/workflows/ci.yml）はこのパッケージのみを対象にしている。他スキルは lefthook のローカルフックが検証の主体になる。

設定ファイルへの書き込み（共通原則）

エージェントスキルがユーザーの設定ファイル（settings.json / config.toml / hooks.json 等）を書き換える場合、既存の内容を無条件に上書きしない。差分を提示してから確認を取る、または安全にマージする（cc-trace/SKILL.md の cctrace:init を参照）。認識できない形式のファイルは自動編集を諦め、手動で追記する行だけを提示する。

検証

PR を出す前に、変更したスキルに対応する検証を必ず実行する:

スキル	コマンド
cc-trace（Python）	cd cc-trace && uv run --with pytest python -m pytest tests/ -q
cc-trace（Nushell フック）	bash cc-trace/tests/test_hooks_nu.sh
video-frame-reader	cd video-frame-reader && uv run --with pytest python -m pytest tests/ -q
ci-monitoring	just ci（cd ci-monitoring/packages && bun run fmt && bun run lint && bun run ci と同義）

lefthook の pre-commit は変更ファイルの glob に応じてこれらを自動実行するが、glob 外の関連変更（例: スキーマ変更だけで .nu に触れていない）は手動で流すこと。

Pull Request の書き方

.github/pull_request_template.md の4セクションを埋める:

• 背景・課題 — 今何が壊れている／できないのか。修正内容ではなく現状を書く。
• 方針・変更内容 — 何をどう変えたか、なぜその方法を選んだか（却下した代替案があれば理由も）。
• 影響範囲 — このPRが触るもの、そして明示的に触らないもの。
• 検証 — 上表のうちどれを実行したか、実機での手動確認があればその内容。

Pull Request チェックリスト

• 変更したスキルのフォーマッタ・linter が通る
• 対応するテストを追加・更新した
• tests/ のテストが通る
• SKILL.md / SKILL.ja.md を変更した場合、両方に反映した
• PR 説明が「背景・課題 / 方針・変更内容 / 影響範囲 / 検証」の形式に従っている

バグ報告

Issue には以下を含める:

• 再現手順
• 期待する挙動
• 実際の挙動
• 環境情報（OS、Nushell/uv/Bun のバージョン、Claude Code か Codex CLI か）

セキュリティ

APIトークンや認証情報の扱いに影響する脆弱性を見つけた場合、公開 Issue は避け、メンテナに直接報告すること。