create-repo-local-skill

name	create-repo-local-skill
description	Maintain tgbt repo-local skills under `.agents/skills`. Use for creating, refactoring, validating, or refreshing skill metadata while aligning with tgbt oracle and upstream `$skill-creator`, without editing `CODEX_HOME`.

Create Repo Local Skill

Overview

<tgbt-root>/.agents/skills 配下の repo-local skill を作成、更新、検証する。 upstream の $skill-creator を必ず併用し、repo 固有ルールは <tgbt-root>/AGENTS.md と <tgbt-root>/oracle、Codex skill 一般の根拠は upstream skill-creator と OpenAI 公式 docs で確認する。

Guardrails

• 新規・更新・メンテナンス対象は <tgbt-root>/.agents/skills/<skill-name> 配下に限定する。
• CODEX_HOME 配下には書き込まない。system skill は read と bundled script の実行だけに使う。
• skill は「tgbt 上で AI エージェントが行う目的別作業指示」として書く。tgbt の正本仕様や作業ログを書かない。
• SKILL.md は実行時に必要な指示へ絞る。補足説明用の README.md、docs/、QUICK_REFERENCE.md などは追加しない。
• user が対象 skill を指定していない repo-local skill メンテナンス依頼では、.agents/skills/* 全体を対象にする。

Workflow

1. Load upstream skill-creator

• まず ${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/SKILL.md を読む。
• 初期化、metadata 生成、validation は upstream scripts を優先する。
• UI metadata を触る場合は upstream skill-creator の references/openai_yaml.md も確認する。

2. Check repo-local rules

• <tgbt-root>/AGENTS.md を確認する。
• repo-local skill の原則は、<tgbt-root>/oracle/docs/ROUTING.md、<tgbt-root>/oracle/docs/dev_rule/ROUTING.md、<tgbt-root>/oracle/docs/dev_rule/skills/ROUTING.md を辿って、<tgbt-root>/oracle/docs/dev_rule/skills/general_rule.md と <tgbt-root>/oracle/docs/dev_rule/skills/create_repo_local_skill.md を参照する。
• path 表記、AI 管理ドキュメント、<tgbt-root>/.venv、依存導入、<tgbt-root>/oracle の扱いが論点になる場合だけ、対応する <tgbt-root>/oracle/docs/dev_rule/*.md を読む。

3. Decide targets and mode

• skill 名が指定された場合は、その <tgbt-root>/.agents/skills/<skill-name> だけを対象にする。
• 対象指定なしのメンテナンス依頼では、.agents/skills/* を対象にする。
• 対象が存在しなければ新規作成、存在していて修正・確認が明示されていれば既存更新として扱う。
• 既存 skill があり、user の意図が新規作成か更新か曖昧な場合だけ確認する。
• 既存更新では init_skill.py を再実行しない。

4. Fix the install root and naming

• install 先は常に <tgbt-root>/.agents/skills に固定する。
• upstream が既定で使う $CODEX_HOME/skills は使わない。
• skill 名は lowercase letters, digits, hyphens only の hyphen-case にする。

5. Create new skills

新規作成では upstream の init_skill.py を repo-local path で実行する。

./.venv/bin/python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/init_skill.py" <skill-name> --path .agents/skills

• scripts/, references/, assets/ は、実行時に直接役立つ場合だけ追加または更新する。
• SKILL.md には、対象タスクをどう進めるかの実務原則と repo 固有 guardrails を書く。
• agents/openai.yaml も同時に生成する。

6. Maintain existing skills

既存更新では、既存内容を読んで必要最小限の差分にする。各 skill は次の観点で確認する。

• <tgbt-root>/oracle の明示内容や <tgbt-root>/AGENTS.md と矛盾していないか。
• description が用途、trigger 語、境界を前方に寄せて簡潔に示しているか。
• SKILL.md が実行時に必要な指示へ絞られ、冗長な背景説明を含んでいないか。
• 1 skill 1 job になっており、扱う範囲と扱わない範囲が曖昧でないか。
• 繰り返しが多い、または機械的に検証すべき処理を scripts/ に切り出す余地があるか。
• OpenAI 公式 docs と照らし合わせて、問題または改善余地がないか。
• 一般的な skill ベストプラクティスと照らし合わせて、問題または改善余地がないか。
• bundled resources と agents/openai.yaml が現在の SKILL.md とずれていないか。

OpenAI 公式 docs を参照する場合は、公式ドメインの最新 docs を使う。

7. Generate or refresh UI metadata

• <tgbt-root>/.agents/skills/<skill-name>/agents/openai.yaml が存在しない場合や SKILL.md と明らかにずれている場合は、upstream の generate_openai_yaml.py で生成または再生成する。
• display_name, short_description, default_prompt は対象 skill の用途を読んで決める。
• default_prompt には必ず $<skill-name> を明示する。

./.venv/bin/python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/generate_openai_yaml.py" .agents/skills/<skill-name> --interface display_name="..." --interface short_description="..." --interface default_prompt="Use $<skill-name> ..."

8. Validate

• 最後に upstream の quick_validate.py で対象 skill を検証する。複数 skill をメンテナンスした場合は全件検証する。
• validation に落ちたら、frontmatter と naming と metadata を修正して再実行する。

./.venv/bin/python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" .agents/skills/<skill-name>

Reporting Rules

• 対象 skill 名と、新規作成か既存更新かを明示する。
• 更新した path、参照した主な <tgbt-root>/oracle / 公式 docs / upstream skill-creator、使った upstream script、validation 結果を報告する。編集しない review の場合は、更新なしと findings を明示する。
• CODEX_HOME 配下を編集していないことを明示する。