Create Taskp Skill

taskp スキル作成ガイド

ユーザーの要望をヒアリングし、taskp の SKILL.md 仕様に準拠したスキルファイルを作成する。

仕様の要点

ファイル構造

.taskp/skills/<skill-name>/
└── SKILL.md

• name フィールドとディレクトリ名を一致させること

フロントマター（YAML）

---
name: <skill-name>                    # 必須: ディレクトリ名と一致
description: <説明>                     # 必須: list コマンドで表示される
mode: template | agent                 # 省略時は template
inputs: []                             # 入力定義（actions 定義時は無視される）
model: provider/model                  # agent モード時の LLM モデル（省略可）
tools: [bash, read, write]             # agent モード時のツール（省略可、デフォルト: bash, read, write）
context: []                            # 自動コンテキスト（省略可）
timeout: 30000                         # タイムアウト ms（省略可）
actions:                               # マルチアクション定義（省略可）
  action-name:
    description: <説明>
    mode: agent                        # スキルレベルを上書き可能
    model: provider/model
    inputs: []
    tools: []
    context: []
    timeout: 30000
---

Input 定義

inputs:
  - name: varname         # 変数名（本文で {{varname}} として参照）
    type: text            # text | textarea | select | confirm | number | password
    message: "質問文"
    default: "デフォルト値"  # 省略可
    choices: [a, b, c]    # select 用（省略可）
    required: true        # 省略可（デフォルト: true）
    validate: "^[a-z]+$"  # 正規表現バリデーション（省略可）

Agent ツール

agent モードで使用できるツール一覧：

tools 未指定時は bash, read, write がデフォルトで有効。

taskp_run の制約

• template モードのスキルのみ呼び出し可能（agent のネストは不可）
• 再帰呼び出しは検出・ブロック
• 最大ネスト深度: 3

Context 定義

context:
  - type: file
    path: "src/{{target}}"          # 変数展開可能
  - type: glob
    pattern: "src/**/*.ts"
  - type: command
    run: "git diff --cached"
  - type: url
    url: "https://example.com/docs"
  - type: image
    path: "docs/diagram.png"        # 変数展開可能

画像コンテキスト

type: image は画像ファイルをバイナリ読み込みし、マルチモーダルコンテンツとして LLM に送信する。

対応フォーマット: PNG, JPEG, GIF, WebP（SVG, BMP 等は非対応でエラー）

変数展開

• 構文: {{variable_name}}
• 変数パターン: \w+（英数字とアンダースコアのみ）
• 未定義変数があるとエラーになる

条件ブロック

{{#if var}}...{{/if}} および {{#if var}}...{{else}}...{{/if}} が使える。

{{#if confirm}}
確認済みの処理を実行します。
{{else}}
スキップしました。
{{/if}}

truthy / falsy 判定:

• falsy: 空文字 "" と "false"
• truthy: それ以外すべて（"true", "hello", "0" 等）

制約:

• ネスト不可（{{#if}} の中に {{#if}} を書くとエラー）
• 閉じタグ {{/if}} 必須（なければエラー）
• 選択されなかった分岐内の未定義変数はエラーにならない

予約変数（inputs で定義せずに使える）

マルチアクション

1つのスキルに複数のアクションを定義できる。

actions:
  add:
    description: タスクを追加する
    inputs:
      - name: title
        type: text
        message: "タスク名は？"
  list:
    description: タスク一覧を表示する
  delete:
    description: タスクを削除する
    mode: agent
    tools: [bash, read, grep]
    inputs:
      - name: id
        type: text
        message: "タスクIDは？"

• actions が定義されている場合、スキルレベルの inputs は無視される
• 各アクションは mode, model, inputs, tools, context, timeout を個別に上書き可能（未指定はスキルレベルを継承）
• inputs は継承されない（各アクションで独自に定義）
• 本文中の ## action:<name> セクション（H2 固定）でアクションの実行手順を定義する
• 実行: taskp run skill:action

カスタムシステムプロンプト

agent モードで使用されるシステムプロンプトを SYSTEM.md でカスタマイズできる。

SYSTEM.md が存在する場合、その内容がデフォルトのシステムプロンプトの代わりに使用される。利用可能なツール一覧と環境情報は自動的に付与される。

実行モードの選び方

template モード

• マークダウン内の ```bash コードブロックを上から順に抽出・実行
• 変数展開後に execa で実行
• 非ゼロ終了コードで中断

agent モード

• マークダウン全体を LLM のプロンプトとして送信
• LLM が tools を呼び出して自律実行
• LLM が完了と判断するまでループ
• model 指定: provider/model 形式（例: anthropic/claude-sonnet-4-20250514）
• model 解決順: CLI オプション > スキルの frontmatter > config.toml のデフォルト

作成手順

1. ヒアリング: ユーザーにスキルの目的・用途を聞く
2. モード判定: 確定的な手順か、判断が必要かで template / agent を決める
3. 入力設計: 必要なパラメータを inputs として定義する
4. コンテキスト設計: 自動取得すべき情報があれば context を定義する（画像を含むマルチモーダルタスクには type: image を使う）
5. ツール選定（agent モード）: デフォルトの bash/read/write に加え、必要なツールを選択する
6. アクション設計: 関連する複数の操作がある場合は actions でまとめる
7. 本文作成: 手順書（template）またはプロンプト（agent）を書く
8. ファイル出力: .taskp/skills/<name>/SKILL.md に書き出す

注意事項・よくある落とし穴

• 変数名は \w+ のみ: ハイフンやドットは使えない（my_var は OK、my-var は NG）
• {{#if}} はネスト不可: {{#if a}}{{#if b}}...{{/if}}{{/if}} はエラーになる。フラットに並べること
• {{/if}} の閉じ忘れはエラー: サイレントに壊れることはない
• confirm 型は {{#if}} と組み合わせる: {{#if confirmed}}実行{{else}}スキップ{{/if}}
• required: false の空入力も {{#if}} で判定可能: 空文字は falsy になる
• "0" は truthy: falsy は "" と "false" のみ
• context 内のパスも変数展開される: path: "src/{{target}}" のように動的パスが使える
• name とディレクトリ名を一致させる: 不一致だとスキルが見つからない
• template モードでは bash コードブロックのみ実行される: 他の言語のコードブロックは無視される
• スキルディレクトリにヘルパースクリプトを置ける: {{__skill_dir__}}/script.sh で参照可能
• 画像コンテキストは対応フォーマットのみ: PNG, JPEG, GIF, WebP 以外はエラーになる
• actions 定義時は inputs が無視される: 各アクションで個別に定義すること