@springbrand/cli 0.1.7-alpha.1 → 0.1.7-alpha.2

package/skill/use-springbrand/SKILL.md

@@ -1,26 +1,127 @@
 ---
 name: use-springbrand
-description: Use SpringBrand through the configured MCP server when the user needs a Platform operation, an Action API, or a connected third-party service. Discover the operation with search_tools, then use its current schema and the appropriate Domain Skill.
+description: Use SpringBrand through the configured MCP server for Agent creation and runs, Platform operations, Action APIs, or connected third-party services. Agent and crawler requests use build_agent directly; other operations use search_tools and their current schema.
 ---
 
 # SpringBrand MCP
 
-Use the configured MCP server named `springbrand` for SpringBrand work. The
-CLI owns installation, endpoint configuration, and API-key authentication. Do
-not ask the user to copy credentials into a prompt or configure a second MCP
-server.
+{{SPRINGBRAND_SERVER_GUIDANCE}}
+
+## Build and run an Agent
+
+The development Agent demo adds three direct tools alongside the five general
+Meta Tools. Use this workflow when the user wants to create, build or set up
+a SpringBrand Agent, a crawler or data collection Agent, or a repeatable or
+recurring collection job such as "collect these topics every day".
+These three tools are not returned by `search_tools`; call them directly
+when the connected server exposes them.
+Do not replace an Agent request with a one-off Action or search for Agent
+creation as a business operation.
+
+| Tool | Use |
+| --- | --- |
+| `build_agent` | List sites supported by current SpringBrand Actions, then create a crawler Agent. No run or Credit spend. |
+| `run_agent` | Open a Chat with the created Agent and send the concrete task as its first message. Starting a run costs Credits. |
+| `get_agent_result` | Block for up to 10 minutes for the final answer or current status. Read-only; no Credit spend. |
+
+1. Call `build_agent` with `step: "list_sites"` to discover supported sites.
+   Guide the user toward those sites or the listed general web scrapers.
+2. Ask at most one short round about the Agent's sites, data fields and output
+   format. Write complete English instructions, show a short summary and get
+   confirmation. Do not require this run's keywords, accounts or URLs yet.
+3. Call `build_agent` with `step: "create"` and the chosen site IDs in
+   `dataSources`. Only report creation after a successful response with the
+   actual Agent ID; preparing a local configuration file is not creation.
+4. Tell the user the Agent's name, sites and Agent Studio URL, then
+   ask what the user wants the Agent to do now:
+   concrete keywords, accounts, URLs, quantity or time range.
+5. After the user supplies the task and wants it run, call `run_agent` with
+   the returned `agent.id` as `agentId` and that task as `prompt`.
+6. If started successfully, tell the user the conversation has started.
+   Include the returned `chatId` and website URL: they can ask you to query
+   progress and results by ID or view the Chat on the SpringBrand website.
+7. Call `get_agent_result` with that Chat ID. It blocks for up to 10 minutes,
+   polling internally and returning early for a terminal or attention status.
+   If the wait expires with status `running`, repeat with the same ID;
+   do not start another run. For `completed`, return
+   the final answer and Chat URL. For `failed` or `cancelled`, report the
+   reason and URL. For `needs_attention`, show the question or approval and
+   ask the user to handle it in the web Chat before querying again.
+
+### Scheduled tasks
+
+When the user asks for a scheduled task, first create an ordinary Agent using
+the workflow above. No special scheduled-Agent type is needed. Then call
+`run_agent` with a `prompt` explicitly asking the Agent to create the scheduled
+task, rather than merely asking it to collect data once.
+
+Include the actual task, frequency, run time, time zone and output requirements.
+Reuse details the user has already supplied; after Agent creation, ask only for
+missing task or timing details. For example:
+
+```text
+Create a scheduled task that collects 20 Xiaohongshu posts about camping gear every day at 09:00 in Asia/Shanghai. Each report should include a table with titles, authors and source links, plus a short summary. Confirm the schedule and its time zone after creating it.
+```
+
+Do not search for a separate scheduling MCP tool or create local cron jobs.
+Creating an Agent or starting a Chat does not confirm that a scheduled task exists.
+Read the Agent's response with `get_agent_result`; only report schedule creation
+when that response confirms it. Relay the confirmed timing, any returned task
+identifier and the Chat URL, or explain the unresolved request or failure.
+
+Use the user's language for replies. Follow the current tool schemas and
+returned guidance. Creating a reusable Agent does not configure a schedule
+by itself; the explicit request in the subsequent Chat delegates that work
+to the Agent.
+
+The client's tool-call timeout must be longer than 10 minutes, for example
+15 minutes. This is a client requirement, not a setting the server can change.
+The updated CLI sets at least 900 seconds in its generated Codex Plugin's
+SpringBrand server configuration. Other clients and the older native Codex
+fallback still need an equivalent timeout setting.
+Do not inspect or modify local client configuration without user permission.
+
+## Check actual tool availability
+
+Never infer loaded tool names or counts from this Skill. Use the client's
+live tool list or tool-discovery interface when available. A successful CLI
+installation or authentication check does not prove that the current
+conversation has loaded any MCP tools.
+
+If the direct Agent tools are unavailable, explain that creation cannot be
+performed in this conversation; do not fall back to a one-off Action or
+claim that an Agent was created. Do not report zero tools solely because
+you have not inspected the client's live tool-discovery interface. Keep
+"not yet discovered" distinct from "confirmed unavailable".
 
 ## Start with discovery
 
-When the user asks what SpringBrand can do or asks you to perform an external
-operation, call `search_tools` with one concise English query. Preserve the
+For operations other than the direct Agent workflow, when the user asks what
+SpringBrand can do or asks you to perform an external operation, call
+`search_tools` with one concise English query. Preserve the
 requested service, operation, and important constraints. `search_tools` is a
 bounded relevant-operation search, not a complete catalog; only a complete
 empty result establishes no match.
 
-Use the returned opaque Tool ID unchanged. Call `get_tool_schemas` before an
-execution unless a current contract is already available. Build arguments
-strictly from that schema and ask the user for missing business values.
+The five Meta Tools are general entry points, not the capability list or
+an exhaustive MCP tool list. The development Agent tools are described
+separately above. Plugins, Action APIs, and connected-service operations are
+visible only through `search_tools`. For these discoverable operations, never
+tell the user that SpringBrand lacks a capability unless you called
+`search_tools` for it in this task and the result was empty with
+`complete: true`. When a result is incomplete or has no fitting candidate,
+narrow or revise the English query and search again, at most three searches
+for one need; do not fan out synonym variants in parallel.
+
+Use the returned opaque Tool ID unchanged. For a chargeable Action candidate,
+read its current contract with `get_tool_schemas`, build arguments strictly
+from that schema and the user's request, then call the returned read-only
+Credit estimate operation before showing the candidate for selection. Report
+`estimatedCredits` or an explicitly unavailable cost together with
+`requiredReservationCredits`, and wait for the user's choice. Ask for missing
+business values before estimating. For a known non-chargeable operation, call
+`get_tool_schemas` before execution unless a current contract is already
+available.
 
 ## The five Meta Tools
 
@@ -32,9 +133,10 @@ strictly from that schema and ask the user for missing business values.
 | `execute_tools` | Run one discovered operation with schema-valid arguments and a stable idempotency key. |
 | `get_execution` | Read an exact saved execution result or status. |
 
-The tools are independently composable. Do not invent a fixed sequence when
-the user already has a current Tool ID, schema, connection pointer, or
-execution ID.
+The tools remain independently composable when the user already has the exact
+Tool ID, current contract, connection pointer, or execution ID. For a new
+chargeable Action choice, preserve the search → schema → estimate → user
+choice → execute order so the user sees the cost before any charge.
 
 ## Choose the workflow guidance
 
@@ -54,9 +156,14 @@ workflow.
 
 - Copy Tool IDs, execution IDs, connection IDs, and authorization attempt IDs
   exactly as returned. Never parse or reconstruct them.
-- Execute only with the current contract, schema-valid arguments, and a stable
-  idempotency key for the logical run.
+- Execute discovered operations only with the current contract, schema-valid
+  arguments, and a stable idempotency key for the logical run. Direct Agent
+  calls follow their own schemas and the workflow above.
 - Explain known cost, risk, approval, and access requirements before a write.
+- re-estimate a chargeable Action when its target, arguments, or revision
+  changes. A result-dependent or unavailable estimate is not a price; wait for
+  the user's explicit decision before executing it. Report `chargedCredits`
+  from the completed result when present.
 - Treat `outcome_unknown` as uncertain. Preserve its idempotency identity and
   verify the external effect; never retry automatically.
 - A lookup failure is not proof that an operation failed, and a missing
@@ -64,6 +171,8 @@ workflow.
 
 ## Results
 
-Only `succeeded` means an operation completed. A running or queued execution
-remains in progress; use `get_execution` only with the exact returned ID. Use
-the selected Tool description and returned contract to interpret its result.
+For discovered operations, only `succeeded` means an operation completed.
+A running or queued execution remains in progress; use `get_execution` only
+with the exact returned ID. Use the selected Tool description and returned
+contract to interpret its result.
+Agent runs instead use `get_agent_result` and its statuses described above.