milánhorvatovic/skill-system-foundry

Skill System Foundry

AIエージェント非依存のスキルシステムを構築するためのメタスキル。スキルとロールの二層アーキテクチャ、テンプレート、検証ツール、クロスプラットフォームのオーサリングガイダンスを提供します。Agent Skills仕様に基づいています。

プロジェクトのコンテキスト

このリポジトリには1つのスキル（skill-system-foundry/）とそのテストスイート（tests/）が含まれています。このスキルはメタスキルであり、そのドメインは他のスキルを構築することです。アプリケーションではありません。サーバー、データベース、フロントエンドはありません。

言語: Python 3.12+（標準ライブラリのみ — プロダクションコードにサードパーティのインポートはありません）。

開発依存: coverage（テストカバレッジ測定のみ。正確なバージョンは requirements-dev.txt を参照）。

リポジトリ構造:

.
├── AGENTS.md                        ← このファイル
├── CLAUDE.md                        ← AGENTS.mdへのシンボリックリンク
├── CONTRIBUTING.md                  ← コントリビューターガイドライン
├── README.md                        ← リポジトリ概要
├── .coveragerc                      ← カバレッジ設定（70%閾値、ブランチ）
├── .python-version                  ← Pythonバージョン（現在の値はファイル参照）
├── requirements-dev.txt             ← カバレッジのみ
├── skill-system-foundry/            ← メタスキル本体
│   ├── SKILL.md                     ← エントリポイント（ルーター）
│   ├── README.md                    ← スキルドキュメント
│   ├── capabilities/                ← 自己完結型機能モジュール
│   │   ├── skill-design/
│   │   │   └── capability.md        ← スキル、機能、ロール、マニフェストを作成
│   │   ├── validation/
│   │   │   └── capability.md        ← スキルを検証、システムを監査
│   │   ├── migration/
│   │   │   └── capability.md        ← フラットスキルをルーターパターンに移行
│   │   ├── bundling/
│   │   │   └── capability.md        ← スキルをzipバンドルにパッケージ化
│   │   └── deployment/
│   │       ├── capability.md        ← ツール、ラッパー、シンボリックリンクにデプロイ
│   │       └── references/
│   │           └── symlink-setup.md ← プラットフォーム固有のシンボリックリンクコマンド
│   ├── references/                  ← 必要に応じてコンテキストにロードされるガイダンス
│   │   ├── authoring-principles.md  ← クロスプラットフォームのスキル記述に関する合意
│   │   ├── architecture-patterns.md ← スタンドアロンvsルーターの判断
│   │   ├── agentskills-spec.md      ← 仕様準拠ガイド
│   │   ├── tool-integration.md      ← ツール固有のパスとデプロイ方法
│   │   ├── directory-structure.md   ← 完全なレイアウトと規約
│   │   ├── anti-patterns.md         ← よくある間違い
│   │   ├── claude-code-extensions.md
│   │   ├── codex-extensions.md
│   │   └── cursor-extensions.md
│   ├── assets/                      ← スキャフォールディング用テンプレート
│   │   ├── skill-standalone.md
│   │   ├── skill-router.md
│   │   ├── capability.md
│   │   ├── role.md
│   │   └── manifest.yaml
│   └── scripts/                     ← 検証、スキャフォールディング、バンドルツール
│       ├── lib/                     ← 共有ロジック（モジュール単一責任）
│       │   ├── configuration.yaml   ← すべての検証ルールの単一情報源
│       │   ├── constants.py         ← YAMLをロードし、Python定数として公開
│       │   ├── validation.py        ← 共有の名前/フィールド検証
│       │   ├── references.py        ← 参照スキャンとグラフ探索
│       │   ├── bundling.py          ← コアバンドルロジック
│       │   ├── manifest.py          ← マニフェストの解析と検証
│       │   ├── codex_config.py      ← Codex agents/openai.yamlの検証
│       │   ├── yaml_parser.py       ← 標準ライブラリのみのYAMLサブセットパーサー
│       │   ├── frontmatter.py       ← YAMLフロントマター抽出
│       │   ├── reporting.py         ← 構造化出力フォーマット
│       │   └── discovery.py         ← スキルディレクトリの発見
│       ├── validate_skill.py        ← 単一スキルの検証
│       ├── audit_skill_system.py    ← スキルシステム全体の監査
│       ├── scaffold.py              ← テンプレートから新しいコンポーネントをスキャフォールディング
│       └── bundle.py                ← 配布用バンドル（zip）
├── tests/                           ← 包括的なテストスイート（現在のファイルはtests/参照）
│   ├── helpers.py                   ← 共有テストユーティリティ
│   └── test_*.py                    ← ソースモジュールごとに1つのテストファイル
├── .agents/                         ← 内部開発スキル（配布対象外）
│   └── skills/
│       ├── commit-conventions/       ← コミットメッセージの形式と規約
│       ├── critique/                ← 計画と解決策への建設的な批判
│       ├── git-release/             ← リリースライフサイクルガイダンス
│       ├── github-actions/          ← CI/CDワークフローの作成とレビュー
│       ├── local-code-review/       ← ローカル自動チェックと差分分析
│       ├── markdown-docs/           ← ドキュメント品質の徹底
│       ├── python-scripts/          ← Pythonコード品質の規約
│       ├── review/                  ← 人間によるPRレビュープロセスガイダンス
│       ├── shell-scripts/           ← シェルスクリプトの安全性と一貫性
│       ├── skill-authoring/         ← メタスキル構造の一貫性
│       ├── solution-design/         ← 実装前のソリューション計画
│       ├── validate-skill-spec/     ← スキル構造と仕様準拠の検証
│       └── yaml-config/             ← configuration.yamlのガバナンス
├── .claude/                         ← Claude Codeの設定とスキルシンボリックリンク
│   └── skills/                      ← .agents/skills/へのシンボリックリンク（Claude Code用）
├── .claude-plugin/                  ← Claude Codeプラグインマーケットプレイスの設定
│   ├── plugin.json
│   └── marketplace.json
└── .github/
    ├── codex/                       ← Codexレビュー設定
    │   └── review-reference.md      ← リポジトリ固有のレビューガイダンス
    ├── scripts/                     ← CIヘルパースクリプト（bash + Python）
    ├── workflows/                   ← GitHub Actions CI/CD
    │   ├── python-tests.yaml        ← テスト + カバレッジ + バッジ更新（ubuntu + windows）
    │   ├── shellcheck.yaml          ← .github/scripts/*.sh を lint
    │   ├── codex-code-review.yaml   ← codex-ai-code-review-action によるCodex PRレビュー
    │   └── release.yml              ← zipをバンドルし、リリースアセットをアップロード
    ├── instructions/                ← Copilot/Codex用のレビュールール
    │   ├── markdown.instructions.md ← `**/*.md` に適用
    │   └── scripts.instructions.md  ← `scripts/**/*.py` に適用
    ├── copilot-instructions.md      ← トップレベルのレビューガイダンス
    └── CODEOWNERS                   ← .github/ にはコードオーナーの承認が必要

制約

これらの制約はコードベース全体で譲れません：

• 標準ライブラリのみ — プロダクションコードに pip install 依存関係はありません。スクリプトはPython 3.12+が利用可能な任意の環境で実行可能でなければなりません。
• Python 3.12互換性 — 3.13以上の機能を使用しないでください。
• 検証ルールはYAMLに — 制限、パターン、予約語は scripts/lib/configuration.yaml にあります。検証ルールをPythonにハードコードしないでください。
• os.pathのみ — pathlib は使用しないでください。両方を混在させないでください。
• すべての関数シグネチャに型ヒント — 組み込みジェネリクス（list、dict、tuple）と X | None を使用してください。
• すべての open() 呼び出しで encoding="utf-8" を指定
• 定数からのエラーレベル — lib/constants.py の LEVEL_FAIL、LEVEL_WARN、LEVEL_INFO を使用し、文字列をハードコードしないでください。
• 検証関数は (errors, passes) タプルを返す — 検証失敗で例外を発生させないでください。
• シェルスクリプトは set -euo pipefail を使用し、先頭で ${VAR:?} を使用して環境変数を検証します。
• アクションはコミットSHAにピン留め — タグではありません。
• すべてのスクリプトエントリポイントは --json をサポート — lib/reporting.py の to_json_output() による機械可読出力。

開発ワークフロー

テストの実行

python -m coverage run -m unittest discover -s tests -p "test_*.py" -v
python -m coverage report

カバレッジ閾値: 70% ブランチカバレッジ (.coveragerc で設定)。CI は ubuntu-latest と windows-latest で Python 3.12 を使用してテストを実行します。

メタスキルの検証

cd skill-system-foundry
python scripts/validate_skill.py . --allow-nested-references --verbose
python scripts/audit_skill_system.py .

--allow-nested-references フラグは、このメタスキルが意図的にネストされた参照を使用しているため必要です。この配布リポジトリでは、監査から skills/ ディレクトリがないことに関する1つの警告が予想されます。

シェルスクリプトのLint

shellcheck .github/scripts/*.sh

コミットメッセージの形式

Update <component> and <component>
Add <new-thing> to <location>
Fix <issue> in <component>

アーキテクチャルール

スキルシステムは正確に2つの層を持ちます：

• スキル — 標準的でAI非依存の知識。焦点を絞ったタスクにはスタンドアロン、複雑なドメインにはルーターを使用。
• ロール — 責任、権限、制約、引き継ぎルールを持つ2つ以上のスキルを構成するオーケストレーション契約。

依存関係は厳密に下方向に流れます: ロール → スキル → 機能。逆方向は決してありません。機能はオプションであり、3つ以上の異なる操作が相互に排他的なトリガーを持つ場合にのみ正当化されます。

コード構成

• エントリポイント (scripts/*.py) — 薄いラッパー: 引数解析、出力フォーマット、sys.exit()。すべてを scripts/lib/ に委譲します。
• ライブラリモジュール (scripts/lib/*.py) — ドメインロジック。専用の出力ヘルパー (reporting.py) 以外では print() や sys.exit() は使用しません。
• 定数 (scripts/lib/constants.py) — Pythonの構造的定数、configuration.yaml からロードされた検証ルール。すべてのYAML値はカスタムパーサーによって文字列として返されます — constants.py で int() を使って変換してください。
• テスト (tests/) — ソースモジュールごとに1つのテストファイル。機能別にグループ化された説明的なクラス名を持つ unittest.TestCase。視覚的な明瞭さのためにセクションセパレーター (# ===...) を使用します。

ドキュメント標準

• 簡潔さ優先 — モデルがまだ持っていないコンテキストのみを追加します。
• スキル説明では三人称 — 「スキルを検証します」であり、「スキルを検証する」ではありません。
• 概念ごとに1つの用語 — ファイル内またはファイル間で同義語を混在させないでください。
• 段階的な開示 — SKILL.md は500行未満、詳細は references/ に、相互参照は1レベル深さまで。
• フロントマター — 複数行の説明には折りたたみブロックスカラー (>) を使用し、特殊文字を引用符で囲みます。
• エラーレベルタグ — 仕様ルールには [spec]、プラットフォーム制限には [platform: X]、規則には [foundry]。

レビューガイダンス

詳細なレビュールールは .github/instructions/ にあります：

ファイル	適用対象	焦点
.github/copilot-instructions.md	すべてのファイル	Agent Skills仕様準拠、アーキテクチャ
.github/instructions/markdown.instructions.md	**/*.md	ドキュメント品質、説明トリガー
.github/instructions/scripts.instructions.md	scripts/**/*.py	コード品質、標準ライブラリのみ、型ヒント

自動検証（validate_skill.py、audit_skill_system.py）は、多くのフロントマター、命名、行数、構造チェックを処理します。手動レビューはそれでも、Markdownファイル参照規則（スキルルート相対パスを含む）、パスの有効性、段階的な開示、説明の品質、アーキテクチャの正当性、意味的一貫性を検証します。

リリースプロセス

バージョンは skill-system-foundry/SKILL.md のフロントマター（metadata.version）にあります。タグは vX.Y.Z としてミラーリングされます。release.yml ワークフローは自動的にzipをバンドルし、リリースアセットとしてアップロードします。タグを付ける前に完全な検証とテストを実行してください。