sindri-extension-guide

Sindri 拡張機能開発ガイド

新機能：拡張機能の機能システム

最近追加（2026年1月）： Sindri では、高度な拡張機能向けのオプションの機能システムがサポートされるようになりました。

• プロジェクトの初期化 - 新しいプロジェクトをセットアップするコマンド（project-init）
• 複数方式の認証 - API キー認証と CLI 認証の両方をサポート（auth）
• ライフサイクルフック - インストール前後およびプロジェクト初期化前後のフック（hooks）
• MCP 統合 - Model Context Protocol サーバーとして登録（mcp）

ほとんどの拡張機能に機能は必要ありません。機能が必要なのは、プロジェクト管理機能を拡張する拡張機能（Claude Flow、Agentic QE、Spec-Kit など）だけです。通常の拡張機能（nodejs、python、docker）はこれまでとまったく同じように動作します。

スラッシュコマンド（推奨）

ドキュメントの更新をすべて含め、確実に拡張機能を作成するには、次のコマンドを使用してください。

コマンド	目的
/extension/new <name> [source]	必要なドキュメント作成ワークフローをすべて含めて新しい拡張機能を作成する
/extension/update-docs <name>	既存の拡張機能のドキュメントを更新する

例：

/extension/new mdflow https://github.com/johnlindquist/mdflow
/extension/update-docs nodejs

これらのコマンドでは、必要なドキュメントの更新をすべて含む完全なワークフローが実行されます。

---

概要

このスキルでは、Sindri 用の宣言型 YAML 拡張機能の作成方法を説明します。拡張機能はbash スクリプトではなく YAML ファイルです。すべての設定は宣言型 YAML 定義によって行います。

ドキュメントの配置場所

重要： 拡張機能を作成した後は、関連するドキュメントを必ず更新してください。

主なドキュメントファイル

種類	パス	目的
スキーマ	v2/docker/lib/schemas/extension.schema.json	拡張機能の検証スキーマ
レジストリ	v2/docker/lib/registry.yaml	拡張機能のマスターレジストリ
プロファイル	v2/docker/lib/profiles.yaml	拡張機能のプロファイル定義
カテゴリ	v2/docker/lib/categories.yaml	カテゴリ定義
拡張機能のドキュメント	docs/extensions/{NAME}.md	拡張機能ごとのドキュメント
カタログ	v2/docs/EXTENSIONS.md	すべての拡張機能の概要
作成ガイド	v2/docs/EXTENSION_AUTHORING.md	詳細な作成リファレンス
スライド	docs/slides/extensions.html	ビジュアルプレゼンテーション

クイックスタートチェックリスト

1. ディレクトリを作成：v2/docker/lib/extensions/{name}/
2. 必須セクションを含む extension.yaml を作成
3. v2/docker/lib/registry.yaml に追加
4. 検証：./v2/cli/extension-manager validate {name}
5. テスト：./v2/cli/extension-manager install {name}
6. ドキュメントを更新（以下の拡張機能作成後のチェックリストを参照）

拡張機能のディレクトリ構成

v2/docker/lib/extensions/{extension-name}/
├── extension.yaml       # Required: Main definition
├── scripts/             # Optional: Custom scripts
│   ├── install.sh       # Custom installation
│   ├── uninstall.sh     # Custom removal
│   └── validate.sh      # Custom validation
├── templates/           # Optional: Config templates
│   └── config.template
└── mise.toml            # Optional: mise configuration

最小限の拡張機能テンプレート

metadata:
  name: my-extension
  version: 1.0.0
  description: Brief description (10-200 chars)
  category: dev-tools
  dependencies: []

install:
  method: mise
  mise:
    configFile: mise.toml

validate:
  commands:
    - name: mytool
      versionFlag: --version
      expectedPattern: "v\\d+\\.\\d+\\.\\d+"

拡張機能の YAML セクション

拡張機能は、必須セクション（metadata、install、validate）と、オプションのセクション（requirements、configure、remove、upgrade、bom、capabilities）で構成されます。

重要：capabilities はオプションです。ほとんどの拡張機能（nodejs、python、docker など）には必要ありません。プロジェクトの初期化、認証、ライフサイクルフック、または MCP 統合が必要な拡張機能だけに capabilities セクションが必要です。

1. メタデータ（必須）

metadata:
  name: extension-name # lowercase with hyphens
  version: 1.0.0 # semantic versioning
  description: What it does # 10-200 characters
  category: dev-tools # see categories below
  author: Your Name # optional
  homepage: https://... # optional
  dependencies: # other extensions needed
    - nodejs
    - python

有効なカテゴリ：

• base - コアシステムコンポーネント
• language - プログラミングランタイム（Node.js、Python など）
• dev-tools - 開発ツール（リンター、フォーマッター）
• infrastructure - クラウド／コンテナツール（Docker、K8s、Terraform）
• ai - AI／ML ツールとフレームワーク
• agile - プロジェクト管理ツール（Jira、Linear）
• database - データベースサーバー
• monitoring - オブザーバビリティツール
• mobile - モバイル SDK
• desktop - GUI 環境
• utilities - 汎用ツール

2. 要件（任意）

requirements:
  domains: # Network access needed
    - api.github.com
    - registry.npmjs.org
  diskSpace: 500 # MB required
  secrets: # Credentials needed
    - GITHUB_TOKEN

3. インストール（必須）

インストール方法を1つ選択してください。

mise（言語ツールに推奨）：

install:
  method: mise
  mise:
    configFile: mise.toml # Reference to mise config
    reshim: true # Rebuild shims after install

apt（システムパッケージ）：

install:
  method: apt
  apt:
    repositories:
      - name: docker
        key: https://download.docker.com/linux/ubuntu/gpg
        url: https://download.docker.com/linux/ubuntu
        suite: jammy
        component: stable
    packages:
      - docker-ce
      - docker-ce-cli

binary（直接ダウンロード）：

install:
  method: binary
  binary:
    url: https://github.com/org/repo/releases/download/v1.0.0/tool-linux-amd64.tar.gz
    extract: tar.gz # tar.gz, zip, or none
    destination: ~/.local/bin/tool

npm（Node.js パッケージ）：

install:
  method: npm
  npm:
    packages:
      - typescript
      - eslint
    global: true

script（カスタムインストール）：

install:
  method: script
  script:
    path: scripts/install.sh
    timeout: 300 # seconds (default: 300)

hybrid（複数の方法）：

install:
  method: hybrid
  hybrid:
    steps:
      - method: apt
        apt:
          packages: [build-essential]
      - method: script
        script:
          path: scripts/install.sh

4. 設定（任意）

configure:
  templates:
    - source: templates/config.template
      destination: ~/.config/tool/config.yaml
      mode: overwrite # overwrite|append|merge|skip-if-exists
  environment:
    - key: TOOL_HOME
      value: $HOME/.tool
      scope: bashrc # bashrc|profile|session

5. 検証（必須）

validate:
  commands:
    - name: tool-name
      versionFlag: --version
      expectedPattern: "\\d+\\.\\d+\\.\\d+"
  mise:
    tools:
      - node
      - python
    minToolCount: 2
  script:
    path: scripts/validate.sh
    timeout: 60

6. 削除（任意）

remove:
  confirmation: true
  mise:
    removeConfig: true
    tools: [node, python]
  apt:
    packages: [package-name]
    purge: false
  script:
    path: scripts/uninstall.sh
  paths:
    - ~/.config/tool
    - ~/.local/share/tool

7. アップグレード（任意）

upgrade:
  strategy: automatic # automatic|manual|none
  mise:
    upgradeAll: true
  apt:
    packages: [package-name]
    updateFirst: true
  script:
    path: scripts/upgrade.sh

8. 部品表（任意ですが推奨）

bom:
  tools:
    - name: node
      version: dynamic # or specific version
      source: mise
      type: runtime
      license: MIT
      homepage: https://nodejs.org

9. 機能（任意 - 高度な拡張機能のみ）

拡張機能に次の機能が必要な場合は、機能を使用してください。

• プロジェクトの初期化 - 新しいプロジェクトをセットアップするコマンド（例：claude-flow init、spec-kit init）
• 認証 - 実行前に API キーまたは CLI 認証を検証する
• ライフサイクルフック - インストール前後、またはプロジェクト初期化時のコマンド
• MCP 統合 - Claude Code 用の Model Context Protocol サーバーとして登録する

ほとんどの拡張機能に機能の追加は不要です。 プロジェクト管理機能を拡張する拡張機能でのみ使用してください。

capabilities:
  # Project initialization (optional)
  project-init:
    enabled: true
    commands:
      - command: "mytool init --force"
        description: "Initialize mytool project"
        requiresAuth: anthropic # or: openai, github, none
        conditional: false # true = only run if condition met

    state-markers:
      - path: ".mytool"
        type: directory
        description: "Mytool configuration directory"
      - path: ".mytool/config.json"
        type: file
        description: "Mytool config file"

    validation:
      command: "mytool --version"
      expectedPattern: "^\\d+\\.\\d+\\.\\d+"
      expectedExitCode: 0

  # Authentication (optional)
  auth:
    provider: anthropic # or: openai, github, custom
    required: false # true = block installation without auth
    methods:
      - api-key # API key in environment variable
      - cli-auth # CLI authentication (e.g., Max/Pro plan)
    envVars:
      - ANTHROPIC_API_KEY
    validator:
      command: "claude --version"
      expectedExitCode: 0
    features:
      - name: agent-spawn
        requiresApiKey: false
        description: "CLI-based features"
      - name: api-integration
        requiresApiKey: true
        description: "Direct API features"

  # Lifecycle hooks (optional)
  hooks:
    pre-install:
      command: "echo 'Preparing installation...'"
      description: "Pre-installation checks"
    post-install:
      command: "mytool --version"
      description: "Verify installation"
    pre-project-init:
      command: "mytool doctor --check"
      description: "Pre-init health check"
    post-project-init:
      command: "echo 'Project initialized'"
      description: "Post-init notification"

  # MCP server registration (optional)
  mcp:
    enabled: true
    server:
      command: "npx"
      args:
        - "-y"
        - "@mytool/mcp-server"
        - "start"
      env:
        MYTOOL_MCP_MODE: "1"
    tools:
      - name: "mytool-action"
        description: "Perform mytool action"
      - name: "mytool-query"
        description: "Query mytool data"

  # Feature configuration (optional, V3+ extensions)
  features:
    core:
      daemon_autostart: true
      unified_config: true
    advanced:
      plugin_system: true
      security_scanning: false

機能のガイドライン：

1. シンプルに保つ - 実際に必要な機能のみを追加する
2. 状態マーカー - 冪等性を確保するため、project-init によって作成されるファイル／ディレクトリを定義する
3. 条件付きコマンド - 任意のセットアップ手順には conditional: true を使用する
4. 複数方式の認証 - 可能であれば API キー認証と CLI 認証の両方に対応する
5. 機能単位の認証 - API キーなしで動作する機能もあります（features 配列を使用してください）

レジストリへの追加

拡張機能を作成したら、v2/docker/lib/registry.yaml に追加してください。

extensions:
  my-extension:
    category: dev-tools
    description: Short description
    dependencies: [nodejs]
    protected: false

検証コマンド

# Validate single extension
./v2/cli/extension-manager validate my-extension

# Validate all extensions
./v2/cli/extension-manager validate-all

# Check extension info
./v2/cli/extension-manager info my-extension

# Test installation
./v2/cli/extension-manager install my-extension

# Check status
./v2/cli/extension-manager status my-extension

よくあるパターン

言語ランタイム（mise ベース）

最適な用途：Node.js、Python、Go、Rust、Ruby

• mise.toml 設定ファイルとともに method: mise を使用する
• configure セクションで適切な環境変数を設定する
• バージョンコマンドで検証する
• 機能の追加は不要です - ツールをインストールするだけです

開発ツール（npm ベース）

最適な用途：TypeScript、ESLint、Prettier

• nodejs 拡張機能に依存させる
• グローバルパッケージとともに method: npm を使用する
• 設定テンプレートを追加する

CLI ツール（バイナリのダウンロード）

最適な用途：GitHub リリース、スタンドアロンバイナリ

• GitHub リリース URL とともに method: binary を使用する
• 展開を処理する（tar.gz、zip）
• バイナリが存在し、実行できることを検証する

複雑なセットアップ（hybrid）

最適な用途：デスクトップ環境、複数手順のインストール

• 順序を指定した手順とともに method: hybrid を使用する
• 柔軟性を高めるため、apt と script を組み合わせる
• remove セクションにクリーンアップを含める
• プロジェクトの初期化が必要でない限り、機能の追加は不要です

AI／プロジェクト管理ツール（機能付き）

おすすめ：Claude Flow、Agentic QE、Spec-Kit

• 適切なインストール方法（mise、script、npm）を使用します
• プロジェクト初期化用の機能セクションを追加します
• 冪等性のための状態マーカー（.claude/、.agentic-qe/、.github/spec.json）を定義します
• 認証設定（anthropic、openai、github、またはなし）を含めます
• インストール後／初期化後のアクション用にライフサイクルフックを追加します
• 拡張機能が Claude Code ツールを提供する場合は、MCP サーバーを登録します
• 拡張機能の例：claude-flow-v3、spec-kit、agentic-qe

現在、機能を使用している拡張機能：

拡張機能	project-init	auth	hooks	mcp	備考
claude-flow-v2	✓	anthropic	✓	✓	安定版、158 以上のエイリアス
claude-flow-v3	✓	anthropic	✓	✓	アルファ版、10 倍のパフォーマンス、15 個のツール
agentic-qe	✓	anthropic	✓	✓	AI を活用したテスト
spec-kit	✓	none	✓	-	GitHub の仕様ドキュメント
agentic-flow	✓	anthropic	✓	✓	マルチエージェントワークフロー

スクリプトのガイドライン

すべてのスクリプトは、次の要件を満たす必要があります。

1. #!/usr/bin/env bash で始めます
2. set -euo pipefail を含めます
3. 成功時は 0、失敗時は 0 以外で終了します
4. $HOME、$WORKSPACE 環境変数を使用します
5. echo 文で進行状況を記録します

例：

#!/usr/bin/env bash
set -euo pipefail

echo "Installing my-tool..."
# Installation commands here
echo "my-tool installed successfully"

トラブルシューティング

問題	解決策
スキーマ検証に失敗する	YAML 構文を確認し、必須フィールドを検証します
依存関係が見つからない	不足している拡張機能を registry.yaml に追加します
インストールがタイムアウトする	script セクションのタイムアウトを増やします
検証に失敗する	expectedPattern の正規表現のエスケープを確認します
権限が拒否される	スクリプトに実行権限が必要です

---

拡張機能のドキュメント作成後チェックリスト

重要： 拡張機能を作成または変更した後は、必ず次のドキュメント更新を完了してください。

必須の更新（常に実施）

• レジストリエントリ - v2/docker/lib/registry.yaml に追加します

  extensions:
    my-extension:
      category: dev-tools
      description: Short description
      dependencies: []
  

• 拡張機能のドキュメント - docs/extensions/{NAME}.md を作成します

  • ファイル名には大文字を使用します（例：NODEJS.md、AI-TOOLKIT.md）
  • 概要、インストール、設定、使用例を含めます
  • VisionFlow の場合：docs/extensions/vision-flow/VF-{NAME}.md

• 拡張機能カタログ - v2/docs/EXTENSIONS.md を更新します

  • 該当するカテゴリの表に追加します
  • 拡張機能のドキュメントへのリンクを含めます

条件付きの更新（該当する場合）

• プロファイル - 拡張機能をプロファイルに追加する場合：

  • v2/docker/lib/profiles.yaml を更新します
  • v2/docs/EXTENSIONS.md 内の関連するプロファイルの説明を更新します

• カテゴリ - 新しいカテゴリを追加する場合：

  • v2/docker/lib/categories.yaml を更新します
  • v2/docker/lib/schemas/extension.schema.json を更新します（category enum）
  • v2/docs/EXTENSIONS.md 内のカテゴリのドキュメントを更新します

• スキーマ - 新しい拡張機能フィールドを追加する場合：

  • v2/docker/lib/schemas/extension.schema.json を更新します
  • docs/SCHEMA.md を更新します
  • このスキルの REFERENCE.md を更新します

• スライド - 拡張機能が注目すべきもの、または特集対象である場合：

  • docs/slides/extensions.html を更新します

VisionFlow 固有の更新

• docs/extensions/vision-flow/README.md を更新します
• docs/extensions/vision-flow/CAPABILITY-CATALOG.md を更新します
• 該当する場合は VisionFlow プロファイルを更新します

更新後の検証

# Validate YAML files
pnpm validate:yaml

# Lint markdown
pnpm lint:md

# Validate extension
./v2/cli/extension-manager validate {name}

---

拡張機能ドキュメントのテンプレート

docs/extensions/{NAME}.md を作成する際は、次のテンプレートを使用します。

# {Extension Name}

{Brief description of what the extension provides.}

## Overview

{More detailed explanation of the extension's purpose and capabilities.}

## Installation

\`\`\`bash
extension-manager install {name}
\`\`\`

## What Gets Installed

- {Tool 1} - {purpose}
- {Tool 2} - {purpose}

## Configuration

{Any configuration options or environment variables.}

## Usage

{Usage examples.}

## Dependencies

{List any extension dependencies.}

## Requirements

- **Disk Space:** {X} MB
- **Network:** {domains accessed}
- **Secrets:** {optional secrets}

## Related Extensions

- {Related extension 1}
- {Related extension 2}

---

参照ファイル

• スキーマ：v2/docker/lib/schemas/extension.schema.json
• レジストリ：v2/docker/lib/registry.yaml
• カテゴリ：v2/docker/lib/categories.yaml
• プロファイル：v2/docker/lib/profiles.yaml
• 例：v2/docker/lib/extensions/*/extension.yaml

フィールドの詳細なリファレンスについては、REFERENCE.md をご覧ください。 完全な例については、EXAMPLES.md をご覧ください。

ヒント： Glob ツールと Grep ツールを使って、現在のドキュメントファイルを動的に検索できます。

# Find all extension docs
ls docs/extensions/*.md

# Find VisionFlow docs
ls docs/extensions/vision-flow/*.md