概要

Skills, CLI, and API

Signal Foundry を agent から使うときの役割分担を、skill router / CLI execution / API contract に分けて説明します。

このページの内容8項目

Signal Foundry は、agent が直接 UI を操作する product ではなく、skill が job を選び、CLI が実行し、API が contract を返す product です。

Skills route.
Identity resolves.
CLI executes.
JSON contracts verify.
UI reads.
Docs support recovery.

Signal Foundry は、この phase では LLM planner を持ちません。Codex / Claude Code の skill が自然文を読み、必要なら人間に質問し、CLI の JSON contract で検証します。

Role Split

Layer	Responsibility	Failure Mode
Skill	自然文の job を正しい workflow / CLI surface に振り分ける	unsupported 条件を隠して保存する
CLI	`--json`、`--help`、`error.hint`、`suggested_next_commands` を返す	prose だけで次の操作を推測する
API	HTTP integration の request / response / error contract を固定する	endpoint ごとに credit / auth boundary が曖昧になる
UI	saved artifact を読む	UI 操作を primary automation surface にする
Docs	job selection と復旧を支える	workflow と reference を混ぜる

Job Routing

ユーザーは surface 名ではなく job で依頼します。skill は最初に job を分類します。

User Job	Route	Why
1 社を調べる	`company-research`	`company_id -> profile -> observations -> filings` が必要
会社群を保存する	`list plan -> estimate -> candidates -> materialize`	saved List と credit boundary が必要
CSV から始める	`source import -> resolve -> list create --from-source`	row の解決状態と ambiguous handling が必要
テーマを探索する	`observations search`	saved List の前に evidence を見たい
有報・セグメントを掘る	`company filings -> filing show -> filing compare`	`artifact_health` / `summary_metrics` / `segment_metrics` を確認してから比較する
credit 失敗を直す	`credits balance` と troubleshooting	実行前に残高と上限を確認する

unsupported / weak / needs_human は結果です。agent が silent 0 件として処理しません。

Golden Workflows

会社、法人、List、evidence、EDINET、有報、公式サイト、source import の依頼では、generic websearch より前に Signal Foundry の capability と route を確認します。

sf version --json --check-update
sf auth show --json
sf data capabilities --json
sf list plan "<query>" --json

Workflow	First Signal Foundry step	When to ask
registry discovery	`sf list plan "兵庫県の建設業の会社" --json`	location / industry / save intent が曖昧、または `route_status=needs_human`
listed + EDINET evidence	`sf list plan "上場企業で売上100億以上、生成AIに関連" --json` -> `sf observations search "生成AI" --source edinet --json`	EDINET本文を根拠にしてよいか不明、または `weak_conditions` が保存判断に影響する
listed filing detail	`sf company filings <companyId> --json` -> `sf filing show <companyId> <filingId> --json`	filing が複数ある、artifact が failed/expected、またはセグメント値の有無を確認したい
website / domain identity	`sf list plan "https://global.toyota/ の会社を調べて" --json` -> `sf companies search global.toyota --json`	URL / domain がない、候補が複数、または seed から list 拡張したい条件がない
narrowed Parallel / web enrichment	`sf list plan -> estimate -> candidates/materialize` or `source import -> list create --from-source`	candidate count、max credits / calls、source type、外部 API 利用可否が未確認
source import	`sf source import -> inspect -> map -> resolve -> review/select -> list create --from-source`	mapping 不足、`multiple_candidates`、`not_found` が多い

Parallel / web は external source adapter after narrowing です。No Find All style broad search。Signal Foundry が候補を route / estimate / preview する前に、generic websearch や Parallel で universe discovery しません。

見る key:

route_status
needs_human
suggested_questions
source_routes
safe_next_commands
plan.weak_conditions
plan.unsupported_conditions
filing.artifact_health
filing.fact_stats
filing.summary_metrics
filing.segment_metrics

CLI Contract

agent-facing command は --json を付けます。保存や credit 消費を伴う command は --execute --max-credits <n> を付けます。

最初に確認するもの:

sf version --json --check-update
sf auth show --json
sf data capabilities --json

実行後に確認するもの:

ok
status
error.code
error.hint
error.suggested_next_commands[]
surface-specific artifact keys

特に agent が分岐に使う stable keys:

saved List preview: rows[], meta.returned_rows
source resolve: run.resolved_count, run.multiple_candidates_count, run.not_found_count, run.review_required_count
company research: company_summary, important_observations, filings, evidence, evidence_gaps, next_actions
watchlist review fallback: reason: latest_diff_unavailable, suggested_next_commands[]

CLI の詳細は Essential Commands を正本にします。

API Contract

API は、CLI ではなく自社 system から直接 integration する時の surface です。

API page は次だけを持ちます。

auth / account scope
request shape
response shape
error code
credit boundary
CLI equivalent

workflow prose は API page に入れません。job の流れは Workflow overview に置きます。

UI Contract

UI は saved artifact を読むための surface です。

Current public UI:

/home/lists
/home/lists/{listId}
/home/research
API key settings
usage / credit-related views

新しい List の作成や agent automation は CLI / API が primary surface です。

Docs Contract

Docs は、agent が迷ったときに戻る recovery surface です。

Docs Type	Holds
Getting Started	first success
Workflows	job completion
CLI	command and JSON keys
API	HTTP contract
Features	shipped surface and boundary
Troubleshooting	error recovery

次に読むページ

job selection: Workflow overview
command sequence: Essential Commands
agent handoff: Codex に docs を渡して進める
/llms.txt: /llms.txt

概要