@geekbeer/minion 2.53.2 → 2.54.1

package/core/lib/capability-checker.js

@@ -1,22 +1,19 @@
 /**
  * Capability checker
  *
- * Detects MCP servers configured in ~/.mcp.json and available CLI tools.
- * Results are cached in memory for 5 minutes to avoid excessive filesystem/process checks.
- * Follows the same caching pattern as llm-checker.js.
+ * Detects MCP servers, installed packages, and environment variables.
+ * Always returns fresh results — called on-demand, not on every heartbeat.
+ *
+ * - MCP servers: parsed from ~/.mcp.json
+ * - Packages: scanned from package managers (apt, npm, pip, etc.)
+ * - Env var keys: collected from minion-local variables/secrets stores
  */
 
 const fs = require('fs')
 const path = require('path')
-const { execSync } = require('child_process')
 const { config } = require('../config')
-const { IS_WINDOWS, buildExtendedPath } = require('./platform')
 const variableStore = require('../stores/variable-store')
-
-const CACHE_TTL_MS = 300000 // 5 minutes
-
-let cachedResult = null
-let cachedAt = 0
+const { scanAllPackages, checkPackages } = require('./package-scanner')
 
 /**
  * Detect MCP servers from ~/.mcp.json.
@@ -39,46 +36,6 @@ function getMcpServers() {
   }
 }
 
-/**
- * Check if a CLI tool is available and get its version.
- * @param {string} name - Tool name (e.g., 'git', 'node')
- * @returns {{ name: string, available: boolean, version?: string }}
- */
-function checkTool(name) {
-  const extendedPath = buildExtendedPath(config.HOME_DIR)
-  const env = {
-    ...process.env,
-    HOME: config.HOME_DIR,
-    ...(IS_WINDOWS && { USERPROFILE: config.HOME_DIR }),
-    PATH: extendedPath,
-  }
-  const execOpts = { encoding: 'utf-8', timeout: 5000, stdio: 'pipe', env }
-
-  try {
-    // Check existence
-    const whichCmd = IS_WINDOWS ? 'where' : 'which'
-    execSync(`${whichCmd} ${name}`, execOpts)
-
-    // Get version
-    let version = null
-    try {
-      const out = execSync(`${name} --version`, execOpts).trim()
-      // Extract version number from output (e.g., "git version 2.43.0" → "2.43.0")
-      const match = out.match(/(\d+\.\d+[\.\d]*)/)
-      if (match) version = match[1]
-    } catch {
-      // Tool exists but --version failed, that's ok
-    }
-
-    return { name, available: true, ...(version && { version }) }
-  } catch {
-    return { name, available: false }
-  }
-}
-
-/** CLI tools to detect */
-const TOOL_NAMES = ['git', 'node', 'npx', 'claude', 'docker', 'tmux']
-
 /**
  * Get all available environment variable keys (variables + secrets).
  * Returns deduplicated key names without values (secrets stay hidden).
@@ -91,38 +48,51 @@ function getEnvVarKeys() {
 }
 
 /**
- * Get all capabilities (MCP servers + CLI tools + env var keys), cached for 5 minutes.
- * @returns {{ mcp_servers: { name: string, configured: boolean }[], cli_tools: { name: string, available: boolean, version?: string }[], env_var_keys: string[] }}
+ * Get all capabilities (MCP servers + installed packages + env var keys).
+ * Always returns fresh results.
+ * @returns {{ mcp_servers: { name: string, configured: boolean }[], packages: Record<string, { available: boolean, items: { name: string, version: string }[] }>, env_var_keys: string[] }}
  */
 function getCapabilities() {
-  const now = Date.now()
-  if (cachedResult && (now - cachedAt) < CACHE_TTL_MS) {
-    return cachedResult
-  }
-
   const mcp_servers = getMcpServers()
-  const cli_tools = TOOL_NAMES.map(name => checkTool(name))
+  const packages = scanAllPackages()
   const env_var_keys = getEnvVarKeys()
 
-  cachedResult = { mcp_servers, cli_tools, env_var_keys }
-  cachedAt = now
-  return cachedResult
-}
-
-/** Clear the cached capability status */
-function clearCapabilityCache() {
-  cachedResult = null
-  cachedAt = 0
+  return { mcp_servers, packages, env_var_keys }
 }
 
 /**
- * Check arbitrary tool names on-demand (not cached).
- * Used by readiness checks to verify skill-declared cli_tools.
- * @param {string[]} names - Tool names to check
- * @returns {{ name: string, available: boolean, version?: string }[]}
+ * Check requirements against current capabilities.
+ * @param {{ mcp_servers?: string[], packages?: Record<string, string[]>, env_vars?: string[] }} requires
+ * @returns {{ satisfied: boolean, missing: { mcp_servers: string[], packages: Record<string, string[]>, env_vars: string[] } }}
  */
-function checkTools(names) {
-  return names.map(name => checkTool(name))
+function checkRequirements(requires) {
+  const missing = { mcp_servers: [], packages: {}, env_vars: [] }
+  let satisfied = true
+
+  // Check MCP servers
+  if (requires.mcp_servers && requires.mcp_servers.length > 0) {
+    const configuredServers = getMcpServers()
+    const configuredNames = new Set(configuredServers.map(s => s.name))
+    missing.mcp_servers = requires.mcp_servers.filter(s => !configuredNames.has(s))
+    if (missing.mcp_servers.length > 0) satisfied = false
+  }
+
+  // Check packages
+  if (requires.packages && Object.keys(requires.packages).length > 0) {
+    const installed = scanAllPackages()
+    const result = checkPackages(requires.packages, installed)
+    missing.packages = result.missing
+    if (!result.satisfied) satisfied = false
+  }
+
+  // Check env vars
+  if (requires.env_vars && requires.env_vars.length > 0) {
+    const envVarKeys = new Set(getEnvVarKeys())
+    missing.env_vars = requires.env_vars.filter(v => !envVarKeys.has(v))
+    if (missing.env_vars.length > 0) satisfied = false
+  }
+
+  return { satisfied, missing }
 }
 
-module.exports = { getCapabilities, clearCapabilityCache, checkTools }
+module.exports = { getCapabilities, checkRequirements }

package/core/lib/package-scanner.js

@@ -0,0 +1,370 @@
+/**
+ * Package scanner
+ *
+ * Scans installed packages from various package managers.
+ * Each scanner checks if the package manager is available, then lists installed packages.
+ * Returns results grouped by package manager with availability status.
+ *
+ * Supported package managers:
+ *   Linux:   apt, npm, pnpm, bun, pip, uv, pipx, cargo
+ *   macOS:   brew, npm, pnpm, bun, pip, uv, pipx, cargo
+ *   Windows: winget, scoop, npm, pnpm, bun, pip, uv, pipx, cargo
+ */
+
+const { execSync } = require('child_process')
+const { IS_WINDOWS, buildExtendedPath } = require('./platform')
+const { config } = require('../config')
+
+/**
+ * Build exec options with extended PATH.
+ * @returns {object}
+ */
+function execOpts() {
+  const extendedPath = buildExtendedPath(config.HOME_DIR)
+  return {
+    encoding: 'utf-8',
+    timeout: 30000,
+    stdio: 'pipe',
+    env: {
+      ...process.env,
+      HOME: config.HOME_DIR,
+      ...(IS_WINDOWS && { USERPROFILE: config.HOME_DIR }),
+      PATH: extendedPath,
+    },
+  }
+}
+
+/**
+ * Check if a command exists.
+ * @param {string} cmd
+ * @returns {boolean}
+ */
+function commandExists(cmd) {
+  try {
+    const whichCmd = IS_WINDOWS ? 'where' : 'which'
+    execSync(`${whichCmd} ${cmd}`, execOpts())
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Run a command and return stdout, or null on failure.
+ * @param {string} cmd
+ * @returns {string | null}
+ */
+function run(cmd) {
+  try {
+    return execSync(cmd, execOpts()).trim()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @typedef {{ name: string, version: string }} PackageItem
+ * @typedef {{ available: boolean, items: PackageItem[] }} ScanResult
+ */
+
+// --- Individual scanners ---
+
+/** @returns {ScanResult} */
+function scanApt() {
+  if (IS_WINDOWS || process.platform === 'darwin') return { available: false, items: [] }
+  if (!commandExists('dpkg-query')) return { available: false, items: [] }
+
+  const out = run("dpkg-query -W -f '${Package}\\t${Version}\\n'")
+  if (!out) return { available: true, items: [] }
+
+  const items = out.split('\n').filter(Boolean).map(line => {
+    const [name, version] = line.split('\t')
+    return { name: name || '', version: version || '' }
+  }).filter(i => i.name)
+
+  return { available: true, items }
+}
+
+/** @returns {ScanResult} */
+function scanBrew() {
+  if (process.platform !== 'darwin') return { available: false, items: [] }
+  if (!commandExists('brew')) return { available: false, items: [] }
+
+  const out = run('brew list --versions')
+  if (!out) return { available: true, items: [] }
+
+  const items = out.split('\n').filter(Boolean).map(line => {
+    const parts = line.split(/\s+/)
+    return { name: parts[0] || '', version: parts.slice(1).join(' ') || '' }
+  }).filter(i => i.name)
+
+  return { available: true, items }
+}
+
+/** @returns {ScanResult} */
+function scanWinget() {
+  if (!IS_WINDOWS) return { available: false, items: [] }
+  if (!commandExists('winget')) return { available: false, items: [] }
+
+  const out = run('winget list --disable-interactivity --accept-source-agreements 2>nul')
+  if (!out) return { available: true, items: [] }
+
+  // winget list output is table-formatted; parse lines after the header separator
+  const lines = out.split('\n')
+  const sepIndex = lines.findIndex(l => /^-{2,}/.test(l.trim()))
+  if (sepIndex < 0) return { available: true, items: [] }
+
+  const items = []
+  for (let i = sepIndex + 1; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (!line) continue
+    // Columns are variable-width; extract name and version heuristically
+    const parts = line.split(/\s{2,}/)
+    if (parts.length >= 2) {
+      items.push({ name: parts[0], version: parts[1] || '' })
+    }
+  }
+
+  return { available: true, items }
+}
+
+/** @returns {ScanResult} */
+function scanScoop() {
+  if (!IS_WINDOWS) return { available: false, items: [] }
+  if (!commandExists('scoop')) return { available: false, items: [] }
+
+  const out = run('scoop list 2>nul')
+  if (!out) return { available: true, items: [] }
+
+  // scoop list output: "  name  version  source  ..."
+  const lines = out.split('\n')
+  const sepIndex = lines.findIndex(l => /^-{2,}/.test(l.trim()))
+
+  const items = []
+  const startIdx = sepIndex >= 0 ? sepIndex + 1 : 0
+  for (let i = startIdx; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (!line || line.startsWith('-')) continue
+    const parts = line.split(/\s+/)
+    if (parts.length >= 2) {
+      items.push({ name: parts[0], version: parts[1] || '' })
+    }
+  }
+
+  return { available: true, items }
+}
+
+/** @returns {ScanResult} */
+function scanNpm() {
+  if (!commandExists('npm')) return { available: false, items: [] }
+
+  const out = run('npm list -g --depth=0 --json')
+  if (!out) return { available: true, items: [] }
+
+  try {
+    const data = JSON.parse(out)
+    const deps = data.dependencies || {}
+    const items = Object.entries(deps).map(([name, info]) => ({
+      name,
+      version: (typeof info === 'object' && info !== null ? info.version : '') || '',
+    }))
+    return { available: true, items }
+  } catch {
+    return { available: true, items: [] }
+  }
+}
+
+/** @returns {ScanResult} */
+function scanPnpm() {
+  if (!commandExists('pnpm')) return { available: false, items: [] }
+
+  const out = run('pnpm list -g --json')
+  if (!out) return { available: true, items: [] }
+
+  try {
+    const data = JSON.parse(out)
+    // pnpm list -g --json returns an array
+    const list = Array.isArray(data) ? data : [data]
+    const items = []
+    for (const entry of list) {
+      const deps = { ...(entry.dependencies || {}), ...(entry.devDependencies || {}) }
+      for (const [name, info] of Object.entries(deps)) {
+        items.push({
+          name,
+          version: (typeof info === 'object' && info !== null ? info.version : '') || '',
+        })
+      }
+    }
+    return { available: true, items }
+  } catch {
+    return { available: true, items: [] }
+  }
+}
+
+/** @returns {ScanResult} */
+function scanBun() {
+  if (!commandExists('bun')) return { available: false, items: [] }
+
+  // bun pm ls -g outputs text format
+  const out = run('bun pm ls -g 2>/dev/null || bun pm ls -g 2>nul')
+  if (!out) return { available: true, items: [] }
+
+  const items = []
+  for (const line of out.split('\n')) {
+    // Lines like: "├── package-name@1.0.0"
+    const match = line.match(/[├└─│\s]*(.+?)@(\S+)/)
+    if (match) {
+      items.push({ name: match[1], version: match[2] })
+    }
+  }
+
+  return { available: true, items }
+}
+
+/** @returns {ScanResult} */
+function scanPip() {
+  // Try pip3 first, then pip
+  const pipCmd = commandExists('pip3') ? 'pip3' : commandExists('pip') ? 'pip' : null
+  if (!pipCmd) return { available: false, items: [] }
+
+  const out = run(`${pipCmd} list --format=json`)
+  if (!out) return { available: true, items: [] }
+
+  try {
+    const data = JSON.parse(out)
+    const items = data.map(pkg => ({
+      name: pkg.name || '',
+      version: pkg.version || '',
+    })).filter(i => i.name)
+    return { available: true, items }
+  } catch {
+    return { available: true, items: [] }
+  }
+}
+
+/** @returns {ScanResult} */
+function scanUv() {
+  if (!commandExists('uv')) return { available: false, items: [] }
+
+  const out = run('uv pip list --format=json 2>/dev/null || uv pip list --format=json 2>nul')
+  if (!out) return { available: true, items: [] }
+
+  try {
+    const data = JSON.parse(out)
+    const items = data.map(pkg => ({
+      name: pkg.name || '',
+      version: pkg.version || '',
+    })).filter(i => i.name)
+    return { available: true, items }
+  } catch {
+    return { available: true, items: [] }
+  }
+}
+
+/** @returns {ScanResult} */
+function scanPipx() {
+  if (!commandExists('pipx')) return { available: false, items: [] }
+
+  const out = run('pipx list --json')
+  if (!out) return { available: true, items: [] }
+
+  try {
+    const data = JSON.parse(out)
+    const venvs = data.venvs || {}
+    const items = Object.entries(venvs).map(([name, info]) => ({
+      name,
+      version: (info && info.metadata && info.metadata.main_package && info.metadata.main_package.package_version) || '',
+    }))
+    return { available: true, items }
+  } catch {
+    return { available: true, items: [] }
+  }
+}
+
+/** @returns {ScanResult} */
+function scanCargo() {
+  if (!commandExists('cargo')) return { available: false, items: [] }
+
+  const out = run('cargo install --list')
+  if (!out) return { available: true, items: [] }
+
+  // Lines like: "ripgrep v14.1.0:" (top-level, no indent = package name)
+  const items = []
+  for (const line of out.split('\n')) {
+    if (line.startsWith(' ') || line.startsWith('\t') || !line.trim()) continue
+    const match = line.match(/^(\S+)\s+v?(\S+):?/)
+    if (match) {
+      items.push({ name: match[1], version: match[2].replace(/:$/, '') })
+    }
+  }
+
+  return { available: true, items }
+}
+
+// --- Scanner registry ---
+
+/**
+ * All supported package manager scanners.
+ * Each scanner handles its own platform check internally.
+ * @type {Record<string, () => ScanResult>}
+ */
+const SCANNERS = {
+  apt: scanApt,
+  brew: scanBrew,
+  winget: scanWinget,
+  scoop: scanScoop,
+  npm: scanNpm,
+  pnpm: scanPnpm,
+  bun: scanBun,
+  pip: scanPip,
+  uv: scanUv,
+  pipx: scanPipx,
+  cargo: scanCargo,
+}
+
+/**
+ * Scan all package managers and return installed packages.
+ * Skips package managers not available on the current platform.
+ * @returns {Record<string, ScanResult>}
+ */
+function scanAllPackages() {
+  const results = {}
+  for (const [name, scanner] of Object.entries(SCANNERS)) {
+    results[name] = scanner()
+  }
+  return results
+}
+
+/**
+ * Check if specific packages are installed for given package managers.
+ * @param {Record<string, string[]>} required - e.g. { apt: ['ffmpeg'], npm: ['@anthropic-ai/claude-code'] }
+ * @param {Record<string, ScanResult>} installed - result from scanAllPackages()
+ * @returns {{ satisfied: boolean, missing: Record<string, string[]> }}
+ */
+function checkPackages(required, installed) {
+  const missing = {}
+  let satisfied = true
+
+  for (const [manager, packages] of Object.entries(required)) {
+    const scan = installed[manager]
+    if (!scan || !scan.available) {
+      // Package manager not available — all packages are missing
+      if (packages.length > 0) {
+        missing[manager] = [...packages]
+        satisfied = false
+      }
+      continue
+    }
+
+    const installedNames = new Set(scan.items.map(i => i.name))
+    const missingPkgs = packages.filter(p => !installedNames.has(p))
+    if (missingPkgs.length > 0) {
+      missing[manager] = missingPkgs
+      satisfied = false
+    }
+  }
+
+  return { satisfied, missing }
+}
+
+module.exports = { scanAllPackages, checkPackages, SCANNERS }

package/core/routes/health.js

@@ -5,14 +5,15 @@
  * - GET  /api/health  - Health check
  * - GET  /api/status  - Get current status
  * - POST /api/status  - Update status
- * - POST /api/capabilities/check-tools - Check arbitrary CLI tools on-demand
+ * - GET  /api/capabilities - Get current capabilities (MCP servers, packages, env vars)
+ * - POST /api/capabilities/check - Check requirements (MCP servers, packages, env vars)
  */
 
 const { version } = require('../../package.json')
 const { config, isHqConfigured } = require('../config')
 const { sendHeartbeat } = require('../api')
 const { getLlmServices, isLlmCommandConfigured } = require('../lib/llm-checker')
-const { getCapabilities, checkTools } = require('../lib/capability-checker')
+const { getCapabilities, checkRequirements } = require('../lib/capability-checker')
 
 function maskToken(token) {
   if (!token || token.length < 8) return token ? '***' : ''
@@ -64,7 +65,6 @@ async function healthRoutes(fastify) {
       timestamp: new Date().toISOString(),
       llm_services: getLlmServices(),
       llm_command_configured: isLlmCommandConfigured(),
-      capabilities: getCapabilities(),
       env: {
         HQ_URL: config.HQ_URL || '',
         MINION_ID: config.MINION_ID || '',
@@ -107,16 +107,21 @@ async function healthRoutes(fastify) {
     return { success: true }
   })
 
-  // Check arbitrary CLI tools on-demand
-  fastify.post('/api/capabilities/check-tools', async (request, reply) => {
-    const { tools } = request.body || {}
-    if (!Array.isArray(tools) || tools.length === 0) {
+  // Get current capabilities (MCP servers, installed packages, env var keys)
+  fastify.get('/api/capabilities', async () => {
+    return getCapabilities()
+  })
+
+  // Check requirements against current capabilities
+  fastify.post('/api/capabilities/check', async (request, reply) => {
+    const { mcp_servers, packages, env_vars } = request.body || {}
+
+    if (!mcp_servers && !packages && !env_vars) {
       reply.code(400)
-      return { error: 'tools must be a non-empty array of tool names' }
+      return { error: 'At least one of mcp_servers, packages, or env_vars must be provided' }
     }
-    // Limit to 20 tools per request to avoid abuse
-    const limited = tools.slice(0, 20).filter(t => typeof t === 'string' && t.length > 0)
-    return { cli_tools: checkTools(limited) }
+
+    return checkRequirements({ mcp_servers, packages, env_vars })
   })
 }
 

package/docs/environment-setup.md

@@ -0,0 +1,199 @@
+# 環境セットアップガイド
+
+スキルが必要とする MCP サーバーや CLI ツールのインストール・設定手順です。
+
+---
+
+## 事前チェック（Readiness Check）の仕組み
+
+スキルの `requires` フロントマターで宣言された依存関係は、ワークフロー実行前に事前チェックされる。
+
+```yaml
+requires:
+  mcp_servers: [playwright]
+  packages:
+    apt: [jq, imagemagick]
+  env_vars: [API_KEY]
+```
+
+| 種別 | 検出方法 | チェック対象 |
+|------|---------|-------------|
+| `mcp_servers` | `~/.mcp.json` を読み取り、`mcpServers` キーにサーバー名が存在するか確認 | 設定ファイルの有無のみ（実際の起動テストはしない） |
+| `packages` | 各パッケージマネージャーの list コマンドでインストール済みパッケージを取得し、突合 | パッケージの存在 |
+| `env_vars` | ミニオンローカル変数/シークレット + HQ注入変数 | キーの存在 |
+
+**重要**: MCP サーバーは `~/.mcp.json` に設定しないと検出されない。npm パッケージをインストールしただけでは不十分。
+
+---
+
+## MCP サーバーの設定
+
+MCP サーバーは `~/.mcp.json` に JSON 形式で設定する。このファイルが Claude Code セッション起動時に読み込まれる。
+
+### ファイル形式
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "command": "<起動コマンド>",
+      "args": ["<引数1>", "<引数2>"]
+    }
+  }
+}
+```
+
+### 設定の追加・変更手順
+
+1. `~/.mcp.json` が存在しない場合は新規作成する
+2. 既存の場合は内容を読み取り、`mcpServers` オブジェクトにエントリを追加する
+3. 既存エントリを壊さないよう注意する
+
+```bash
+# 既存ファイルの確認
+cat ~/.mcp.json 2>/dev/null || echo '(not found)'
+```
+
+### よく使う MCP サーバーの設定例
+
+#### Playwright（ブラウザ自動化）
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+`npx -y` により、未インストールでも自動ダウンロード・実行される。事前の `npm install` は不要。
+
+#### Supabase（データベース）
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "url": "http://<supabase-host>:54321/mcp?read_only=true&features=database,docs"
+    }
+  }
+}
+```
+
+URL ベースの MCP サーバーは `url` フィールドで指定する（`command`/`args` は不要）。
+
+### 注意事項
+
+- `~/.mcp.json` は手動で編集する。Claude Code の設定 UI からは変更できない
+- `npx -y <package>` 形式を使えば、グローバルインストールなしで MCP サーバーを起動できる
+- サーバー名はスキルの `requires.mcp_servers` と一致させる必要がある（例: `playwright`）
+- `claude-settings.json`（`~/.claude/settings.json`）の `mcpServers` に設定しても同様に動作するが、`~/.mcp.json` が推奨
+
+---
+
+## パッケージのインストール
+
+スキルが `requires.packages` で宣言したパッケージは、対応するパッケージマネージャーの list コマンドで検出される。
+
+### パッケージマネージャーの使い分け
+
+| マネージャー | 用途 | インストール先 |
+|-------------|------|---------------|
+| `apt` | OS レベルのツール・ライブラリ | システム全体 (`/usr/bin/` 等) |
+| `npm` | Node.js パッケージ・CLI ツール | `node_modules/` またはグローバル |
+| `npx` | npm パッケージの一時実行 | 一時ディレクトリ（実行後破棄） |
+| `pip` / `pip3` | Python パッケージ | ユーザーディレクトリまたは venv |
+
+### apt（システムパッケージ）
+
+画像処理ツール、テキスト処理ツール、ネットワークツールなど OS レベルのツールに使う。
+
+```bash
+sudo apt update && sudo apt install -y <package-name>
+```
+
+例:
+```bash
+# 画像処理
+sudo apt install -y imagemagick
+
+# JSON 処理
+sudo apt install -y jq
+
+# PDF 処理
+sudo apt install -y poppler-utils
+```
+
+### npm（Node.js CLI ツール）
+
+グローバルインストールで `which` に検出されるようにする。
+
+```bash
+npm install -g <package-name>
+```
+
+例:
+```bash
+# TypeScript コンパイラ
+npm install -g typescript
+
+# Prettier（コードフォーマッター）
+npm install -g prettier
+```
+
+**注意**: MCP サーバーのインストールに `npm install -g` は使わない。MCP サーバーは `~/.mcp.json` に `npx -y` 形式で設定する（前述の MCP サーバー設定を参照）。
+
+### pip / pip3（Python ツール）
+
+```bash
+pip3 install --user <package-name>
+```
+
+`--user` を付けると `~/.local/bin/` にインストールされる。PATH に含まれていることを確認する。
+
+例:
+```bash
+# AWS CLI
+pip3 install --user awscli
+
+# YAML 処理
+pip3 install --user yq
+```
+
+### npx（一時実行）
+
+`npx` はインストールせずに npm パッケージを一時実行する。`packages` の事前チェックでは検出されないため、恒久的に使うツールには `npm install -g` を使うこと。
+
+```bash
+# 一時的な利用（事前チェックでは検出されない）
+npx -y cowsay hello
+
+# 恒久的に必要なら npm install -g を使う
+npm install -g cowsay
+```
+
+---
+
+## インストール後の確認
+
+ツールのインストール後、事前チェックが通るか確認する。
+
+```bash
+# CLI ツールが検出されるか確認
+which <tool-name>
+
+# MCP サーバーが設定されているか確認
+cat ~/.mcp.json | node -e "
+  const cfg = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  const servers = cfg.mcpServers || cfg.servers || {};
+  console.log('Configured MCP servers:', Object.keys(servers).join(', ') || '(none)');
+"
+
+# エージェントのキャパビリティキャッシュをクリアして再検出させる
+# (キャパビリティは 5 分間キャッシュされるため、即座に反映したい場合)
+curl -s -X POST "http://localhost:8080/api/capabilities/clear-cache" \
+  -H "Authorization: Bearer $API_TOKEN"
+```

package/docs/task-guides.md

@@ -23,7 +23,10 @@ name: my-skill
 description: What this skill does
 requires:
   mcp_servers: [playwright, supabase]
-  cli_tools: [git, node]
+  packages:
+    apt: [ffmpeg]
+    npm: ["@anthropic-ai/claude-code"]
+  env_vars: [API_KEY]
 ---
 
 Skill instructions here...
@@ -37,7 +40,8 @@ Skill instructions here...
 | `description` | Yes | スキルの説明 |
 | `requires` | No | 実行に必要な依存関係 |
 | `requires.mcp_servers` | No | 必要な MCP サーバー名のリスト |
-| `requires.cli_tools` | No | 必要な CLI ツール名のリスト |
+| `requires.packages` | No | 必要なパッケージ（パッケージマネージャー別に指定） |
+| `requires.env_vars` | No | 必要な環境変数キーのリスト |
 
 `requires` を宣言すると、ワークフロー実行前にミニオンの環境と照合する事前チェック（readiness check）が行われる。
 未宣言の場合は常に実行可能と見なされる。
@@ -193,6 +197,19 @@ await reportIssue({ title: '...', body: '...', labels: ['bug'] })
 
 ---
 
+## ツール・MCPサーバーのインストール
+
+スキルが `requires` で宣言している MCP サーバーや CLI ツールが不足している場合は、`~/.minion/docs/environment-setup.md` の手順に従ってインストールする。
+
+主なポイント:
+- **MCP サーバー**: `~/.mcp.json` にエントリを追加する（`npm install` ではなく設定ファイルの編集）
+- **CLI ツール**: `apt`（OS ツール）、`npm install -g`（Node.js ツール）、`pip3 install --user`（Python ツール）を使い分ける
+- **確認**: インストール後 `which <tool>` や `cat ~/.mcp.json` で事前チェックが通るか確認する
+
+詳細は `~/.minion/docs/environment-setup.md` を参照。
+
+---
+
 ## トラブルシューティング
 
 ### HQ APIの仕様がわからない

package/linux/server.js

@@ -35,7 +35,7 @@ const PACKAGE_ROOT = path.join(__dirname, '..')
 const { config, validate, isHqConfigured } = require('../core/config')
 const { sendHeartbeat } = require('../core/api')
 const { version } = require('../package.json')
-const { getCapabilities } = require('../core/lib/capability-checker')
+
 const workflowStore = require('../core/stores/workflow-store')
 const routineStore = require('../core/stores/routine-store')
 
@@ -96,7 +96,7 @@ async function shutdown(signal) {
   if (isHqConfigured()) {
     try {
       await Promise.race([
-        sendHeartbeat({ status: 'offline', version, capabilities: getCapabilities() }),
+        sendHeartbeat({ status: 'offline', version }),
         new Promise(resolve => setTimeout(resolve, 3000)),
       ])
     } catch {
@@ -331,14 +331,14 @@ async function start() {
       // Send initial online heartbeat
       const { getStatus } = require('../core/routes/health')
       const { currentTask } = getStatus()
-      sendHeartbeat({ status: 'online', current_task: currentTask, version, capabilities: getCapabilities() }).catch(err => {
+      sendHeartbeat({ status: 'online', current_task: currentTask, version }).catch(err => {
         console.error('[Heartbeat] Initial heartbeat failed:', err.message)
       })
 
       // Start periodic heartbeat
       heartbeatTimer = setInterval(() => {
         const { currentStatus, currentTask } = getStatus()
-        sendHeartbeat({ status: currentStatus, current_task: currentTask, version, capabilities: getCapabilities() }).catch(err => {
+        sendHeartbeat({ status: currentStatus, current_task: currentTask, version }).catch(err => {
           console.error('[Heartbeat] Periodic heartbeat failed:', err.message)
         })
       }, HEARTBEAT_INTERVAL_MS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.53.2",
+  "version": "2.54.1",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/rules/core.md

@@ -92,3 +92,4 @@ Workflow/Routine 実行中は以下も利用可能:
 API仕様やタスク手順の詳細は以下を参照:
 - `~/.minion/docs/api-reference.md` — ローカルAPI・HQ APIの全エンドポイント仕様
 - `~/.minion/docs/task-guides.md` — スキル修正・ワークフロー管理等の手順書
+- `~/.minion/docs/environment-setup.md` — MCPサーバー設定・CLIツールインストール手順

package/win/lib/process-manager.js

@@ -60,6 +60,14 @@ function buildUpdateScript(npmInstallCmd, stopCmd, startCmd) {
   const logPath = path.join(dataDir, 'update-agent.log')
 
   // PowerShell script content: stop → install → start, with logging
+  // The stopCmd kills all child processes of the agent. Since this script
+  // itself is a child of the agent (spawn from Node), we must exclude our
+  // own PID ($PID) to avoid the update script killing itself.
+  const safeStopCmd = stopCmd.replace(
+    /ForEach-Object\s*\{\s*Stop-Process/,
+    'Where-Object { $_.ProcessId -ne $PID } | ForEach-Object { Stop-Process'
+  )
+
   const ps1 = [
     `$ErrorActionPreference = 'Stop'`,
     `$logFile = '${logPath.replace(/\\/g, '\\\\')}'`,
@@ -67,7 +75,7 @@ function buildUpdateScript(npmInstallCmd, stopCmd, startCmd) {
     `Log 'Update started'`,
     `try {`,
     `  Log 'Stopping agent...'`,
-    `  ${stopCmd}`,
+    `  ${safeStopCmd}`,
     `  Start-Sleep -Seconds 3`,
     `  Log 'Installing package...'`,
     `  $out = & cmd /c "${npmInstallCmd} 2>&1"`,

package/win/server.js

@@ -16,7 +16,7 @@ const fastify = require('fastify')({ logger: true })
 const { config, validate, isHqConfigured } = require('../core/config')
 const { sendHeartbeat } = require('../core/api')
 const { version } = require('../package.json')
-const { getCapabilities } = require('../core/lib/capability-checker')
+
 const workflowStore = require('../core/stores/workflow-store')
 const routineStore = require('../core/stores/routine-store')
 
@@ -74,7 +74,7 @@ async function shutdown(signal) {
   if (isHqConfigured()) {
     try {
       await Promise.race([
-        sendHeartbeat({ status: 'offline', version, capabilities: getCapabilities() }),
+        sendHeartbeat({ status: 'offline', version }),
         new Promise(resolve => setTimeout(resolve, 3000)),
       ])
     } catch {
@@ -267,14 +267,14 @@ async function start() {
       // Send initial online heartbeat
       const { getStatus } = require('../core/routes/health')
       const { currentTask } = getStatus()
-      sendHeartbeat({ status: 'online', current_task: currentTask, version, capabilities: getCapabilities() }).catch(err => {
+      sendHeartbeat({ status: 'online', current_task: currentTask, version }).catch(err => {
         console.error('[Heartbeat] Initial heartbeat failed:', err.message)
       })
 
       // Start periodic heartbeat
       heartbeatTimer = setInterval(() => {
         const { currentStatus, currentTask } = getStatus()
-        sendHeartbeat({ status: currentStatus, current_task: currentTask, version, capabilities: getCapabilities() }).catch(err => {
+        sendHeartbeat({ status: currentStatus, current_task: currentTask, version }).catch(err => {
           console.error('[Heartbeat] Periodic heartbeat failed:', err.message)
         })
       }, HEARTBEAT_INTERVAL_MS)