Manifest Generator

マニフェスト生成ツール

Codex を使用してスキル／MCP の説明から機能マニフェストを自動生成します

目的

OpenAI Codex を使用して既存のスキル、MCP、ツール、コンポーネントを分析し、それらの機能マニフェストを自動生成します。説明と実装から前提条件、効果、ドメイン、関係性を推測することで、オーケストレーションシステム全体の立ち上げを支援します。

使用する場面

• 立ち上げ：59 個のスキルと 50 個の MCP のマニフェストを一度に生成します
• 新しいリソース：新しいスキル／MCP の作成時にマニフェストを自動生成します
• 更新：スキルの説明が変更されたときにマニフェストを再生成します
• 検証：生成したマニフェストと既存のものを比較し、差異を検出します

主な機能

• 前提条件の推測：スキルの説明を分析して、使用前に何が必要かを判断します
• 効果の抽出：スキルによって生じる状態変化を特定します
• ドメインの検出：スキルを技術ドメインに分類します
• 関係性の発見：このスキルが有効化、競合、または連携するスキルを推測します
• リスク評価：説明からコスト、レイテンシ、リスクレベルを評価します

入力

inputs:
  skill_path: string # Path to skill directory (e.g., SKILLS/rag-implementer)
  resource_type: string # "skill" | "mcp" | "tool" | "component" | "integration"
  description_file: string # Usually SKILL.md or README.md
  implementation_file: string # Optional: actual code file for validation
  output_path: string # Where to write manifest.yaml (default: same directory)

処理

ステップ 1：ソース資料を読み込む

# Read skill description
DESCRIPTION=$(cat $skill_path/SKILL.md)

# Read implementation if available
if [ -f "$skill_path/index.js" ]; then
  IMPLEMENTATION=$(head -100 $skill_path/index.js)
fi

# Read existing registry entry
REGISTRY_ENTRY=$(jq ".[] | select(.name==\"$skill_name\")" META/skill-registry.json)

ステップ 2：Codex でマニフェストを生成する

codex exec "
Analyze this ${resource_type} and generate a capability manifest.

DESCRIPTION:
${DESCRIPTION}

IMPLEMENTATION (if available):
${IMPLEMENTATION}

REGISTRY ENTRY:
${REGISTRY_ENTRY}

Generate a YAML manifest matching this schema:
$(cat SCHEMAS/capability-manifest.schema.json)

Infer the following:

1. PRECONDITIONS: What files, dependencies, or state must exist?
   Examples:
   - file_exists('package.json')
   - has_dependency('react')
   - env_var_set('OPENAI_API_KEY')
   - not file_exists('.vector-index')

2. EFFECTS: What does this create/modify/delete?
   Examples:
   - creates_vector_index
   - adds_auth_middleware
   - configures_database
   - updates_tests

3. DOMAINS: What technical areas does it touch?
   Examples: rag, auth, api, database, testing, nextjs, react

4. COMPATIBILITY:
   - requires: What must exist first?
   - conflicts_with: What can't coexist?
   - composes_with: What works well together?
   - enables: What does this unlock?

5. RISK ASSESSMENT:
   - cost: free/low/medium/high (API calls, compute)
   - latency: instant/fast/slow (execution time)
   - risk_level: safe/low/medium/high (side effects)

6. SUCCESS SIGNAL: How do we know it worked?
   Examples:
   - 'tests pass'
   - 'file exists: .vector-index'
   - 'HTTP 200 from /api/search'
   - 'can query vector database'

Output ONLY valid YAML. No explanatory text.
"

ステップ 3：検証して書き込む

# Validate generated YAML against schema
npx ajv validate \
  -s SCHEMAS/capability-manifest.schema.json \
  -d /tmp/generated-manifest.yaml

# Write to output location
cp /tmp/generated-manifest.yaml $output_path

Codex プロンプトテンプレート

Analyze this ${kind} and extract capability information:

NAME: ${name}
DESCRIPTION:
${description}

${implementation ? "IMPLEMENTATION:\n" + implementation : ""}

Generate a capability manifest with:

1. PRECONDITIONS (what must be true to use this?):
   - File checks: file_exists('path'), not file_exists('path')
   - Dependency checks: has_dependency('package-name')
   - Env checks: env_var_set('VAR_NAME')
   - State checks: describe project state requirements

2. EFFECTS (what changes does it make?):
   - Use imperative verbs: creates_, adds_, configures_, updates_, removes_
   - Be specific: "creates_vector_index", not "does vector stuff"

3. DOMAINS (what technical areas?):
   - Choose from: rag, auth, api, database, testing, nextjs, react, security, performance, etc.

4. COMPATIBILITY:
   - requires: [list of required capabilities]
   - conflicts_with: [capabilities that can't coexist]
   - composes_with: [capabilities that work well together]
   - enables: [capabilities this unlocks]

5. COST/LATENCY/RISK:
   - cost: free (no API calls), low (< $0.10), medium (< $1), high (> $1)
   - latency: instant (< 1s), fast (< 10s), slow (> 10s)
   - risk_level: safe (no side effects), low (idempotent), medium (modifies files), high (irreversible changes)

6. SUCCESS_SIGNAL: What confirms it worked?

Output as YAML matching capability-manifest schema.

出力例

# SKILLS/rag-implementer/manifest.yaml
name: rag-implementer
kind: skill
description: Implement retrieval-augmented generation systems with vector databases and embedding pipelines
preconditions:
  - check: file_exists('package.json')
    description: Node.js project with package.json
    required: true
  - check: not file_exists('.vector-index')
    description: Vector database not already configured
    required: false
  - check: env_var_set('OPENAI_API_KEY') or env_var_set('ANTHROPIC_API_KEY')
    description: LLM API key for embeddings
    required: true
effects:
  - creates_vector_index
  - adds_embedding_pipeline
  - configures_retrieval_api
  - adds_rag_tests
domains:
  - rag
  - ai
  - search
  - embeddings
  - api
cost: medium
latency: slow
risk_level: low
side_effects:
  - modifies_files
  - makes_api_calls
idempotent: false
success_signal: 'Vector index created and queryable with test embeddings'
failure_signals:
  - 'API key invalid'
  - 'Vector database connection failed'
  - 'Embedding generation failed'
compatibility:
  requires:
    - openai-integration OR anthropic-integration
  conflicts_with:
    - existing-vector-database
  composes_with:
    - pinecone-mcp
    - weaviate-mcp
    - embedding-generator-mcp
  enables:
    - semantic-search
    - document-qa
    - knowledge-retrieval
observability:
  logs:
    - 'Embedding X documents'
    - 'Vector index created with Y dimensions'
    - 'Retrieval query: {query} returned {count} results'
  metrics:
    - embedding_count
    - retrieval_latency_ms
    - search_relevance_score
metadata:
  version: '1.0.0'
  created_at: '2025-10-28'
  tags:
    - rag
    - vector-database
    - embeddings
    - semantic-search
  examples:
    - 'Implement RAG for Next.js documentation site'
    - 'Add semantic search to existing API'
    - 'Build document Q&A system'

ブートストラップスクリプト

すべてのリソースのマニフェストを生成するには、次を実行します。

#!/bin/bash
# scripts/bootstrap-manifests.sh

echo "Generating manifests for all skills..."
for skill_dir in SKILLS/*/; do
  skill_name=$(basename "$skill_dir")
  echo "  Processing $skill_name..."

  # Use manifest-generator skill
  bash scripts/skills/manifest-generator.sh \
    --path "$skill_dir" \
    --type "skill" \
    --description "$skill_dir/SKILL.md" \
    --output "$skill_dir/manifest.yaml"
done

echo "\nGenerating manifests for all MCPs..."
for mcp_dir in MCP-SERVERS/*/; do
  mcp_name=$(basename "$mcp_dir")
  echo "  Processing $mcp_name..."

  bash scripts/skills/manifest-generator.sh \
    --path "$mcp_dir" \
    --type "mcp" \
    --description "$mcp_dir/README.md" \
    --implementation "$mcp_dir/index.js" \
    --output "$mcp_dir/manifest.yaml"
done

echo "\nDone! Generated $(find SKILLS MCP-SERVERS -name 'manifest.yaml' | wc -l) manifests"

利点

1. 速度：109 個のマニフェストを数週間ではなく数分で生成します
2. 一貫性：形式と網羅性を統一します
3. 発見：Codex が人間の見落とす関係性を発見します
4. 検証：比較によって説明と実装の差異を検出します
5. 進化：スキルの変更に応じて再実行し、更新できます

統合

capability-graph-builder との連携

マニフェストは機能グラフのノードになります。互換性フィールドから関係性が推測されます。

orchestration-planner との連携

プランナーはマニフェストを照会し、目標の要件に合致する機能を見つけます。

skill-validator との連携

バリデーターは生成されたマニフェストと実際の実装を比較し、不一致を見つけます。

成功指標

• ✅ すべてのスキル／MCP にマニフェストがある
• ✅ すべてのマニフェストがスキーマに適合している
• ✅ 前提条件が実際の要件の 90% 以上を網羅している
• ✅ 効果が状態変化を正確に記述している
• ✅ 関係性の推測精度が 80% 以上である

関連スキル

• capability-graph-builder：マニフェストを取り込んでグラフを構築します
• skill-validator：マニフェストが実装と一致しているか検証します
• orchestration-planner：マニフェストを計画に使用します