@agentearth.ai/cli 0.1.0-beta.3 → 0.1.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentearth.ai/cli",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Agent-first CLI that helps AI agents discover, inspect, and execute AgentEarth tools from any shell.",
   "type": "module",
   "bin": {

package/skills/agentearth/SKILL.md

@@ -1,30 +1,92 @@
-# AgentEarth CLI Skill
+---
+name: agentearth
+description: >-
+  Discover, inspect, and execute AgentEarth marketplace tools through the AgentEarth CLI.
+  Use when the user explicitly asks to use AgentEarth/agentearth, asks for AgentEarth tools,
+  or needs an external tool workflow such as live data retrieval, structured web/API results,
+  document or media conversion, translation, calculations, image/video generation,
+  presentation editing, or other tool-backed services. Follow host approval, credential,
+  network, and safety policies before invoking external commands.
 
-Use AgentEarth CLI when the user asks you to discover, inspect, or execute AgentEarth tools.
+requirements:
+  env:
+    - AGENTEARTH_API_KEY
 
-## Commands
+credentials:
+  type: api_key
+  env: AGENTEARTH_API_KEY
+  injection: environment
+  required: true
+---
 
-- Use `ae list` when the user task clearly belongs to a known tool category, such as image generation, video generation, or PPT editing.
-- For filtered list queries, write the query JSON to `query.json` and run `ae list @query.json`; do not hand-write inline JSON in PowerShell.
-- Use `ae recommend "<query>"` when the user task is ambiguous and you are not sure which tool category should be used.
-- Use `ae detail <tool_name>` before execution to read the tool input schema.
-- Use `ae execute <tool_name> @params.json` to execute the selected tool.
-- Use `ae update` only after the user confirms they want to update the CLI.
+# AgentEarth
 
-## Rules
+Use AgentEarth as an external tool marketplace. Treat the user's request as the task to solve, then discover the best matching tool, inspect its schema, validate parameters, execute it, and summarize the result.
 
-- All agent-facing commands output JSON by default.
-- Select tools by `tool_name`.
-- Do not use `tool_url` as an argument.
-- Do not call the removed `ae schema` command.
-- Do not pass API keys to normal tool commands; `ae login` stores credentials for later use.
-- If login is required, read the API key only from the caller-provided `AGENTEARTH_API_KEY` environment variable and pipe it to `ae login --api-key-stdin`; do not search the filesystem for API keys.
+## Command Surface
 
-## Typical Flows
+Prefer `ae` on Unix-like shells and `ae.cmd` in Windows PowerShell when the PowerShell shim is blocked by execution policy.
 
-Known category:
+Use these commands:
 
-Create `query.json`:
+- `ae recommend "<task>"` to discover tools for ambiguous or natural-language tasks.
+- `ae list @query.json` to list tools for a known category or keyword.
+- `ae detail <tool_name>` to inspect a selected tool's schema before execution.
+- `ae execute <tool_name> @params.json` to run the selected tool with validated parameters.
+- `ae update` only when the user confirms they want to update the CLI.
+
+All agent-facing commands return JSON by default. Select tools by `tool_name`; never use `tool_url` as a CLI argument. Do not call removed or undocumented commands such as `ae schema`.
+
+## Credential Handling
+
+Use credentials only through the active host environment.
+
+- Read the API key from `AGENTEARTH_API_KEY` when the host provides it.
+- If login is required, pipe the caller-provided key to `ae login --api-key-stdin`.
+- Never ask the user to paste a key unless the host explicitly requires manual credential setup.
+- Never search the filesystem, shell history, logs, or config files for API keys.
+- Never print, log, echo, or include secrets in generated files.
+
+If authentication fails, report that AgentEarth authentication failed and ask the user to verify the configured API key or login state. Do not expose request headers or secret values.
+
+## Execution Workflow
+
+1. Restate the task internally as a concise AgentEarth query.
+2. Discover candidate tools with `ae recommend "<task>"`, or `ae list @query.json` when the category is already clear.
+3. Inspect the best candidate with `ae detail <tool_name>`.
+4. Build `params.json` strictly from the inspected input schema.
+5. Validate required fields, types, enums, formats, and `additionalProperties` when present.
+6. Execute with `ae execute <tool_name> @params.json`.
+7. Summarize the useful result for the user and omit internal command noise unless it is needed for troubleshooting.
+
+Use a fallback tool only when the first suitable tool fails for a recoverable reason or clearly does not satisfy the task.
+
+## Tool Selection
+
+Choose the tool that best matches the task intent and can be safely executed with available context.
+
+Prefer candidates with:
+
+- clear task relevance;
+- complete and understandable input schema;
+- required parameters that can be filled from the user's request or conversation context;
+- lower cost when otherwise equivalent;
+- narrower, more specialized behavior for the requested job.
+
+If no candidate is suitable, refine the query once. If discovery still fails, tell the user that AgentEarth did not return a suitable tool.
+
+## Parameter Rules
+
+Build parameter files as JSON objects matching the selected tool schema.
+
+- Use only values from the user's request, conversation context, or deterministic transformations of those values.
+- Do not invent required values such as URLs, IDs, tokens, locations, dates, file paths, or account-specific inputs.
+- Ask a concise clarification question when a required value is missing.
+- Remove keys not defined by the schema when `additionalProperties` is `false`.
+- Do not reuse example keys unless they exist in the selected schema.
+- Write query or execution payloads to JSON files instead of hand-writing inline JSON in PowerShell.
+
+Known-category list example:
 
 ```json
 {"keyword":"image"}
@@ -36,10 +98,29 @@ ae detail <tool_name>
 ae execute <tool_name> @params.json
 ```
 
-Ambiguous task:
+Ambiguous-task example:
 
 ```text
-ae recommend "<user task>"
+ae recommend "find current hotel prices in Sapporo for next weekend"
 ae detail <tool_name>
 ae execute <tool_name> @params.json
 ```
+
+## Error Handling
+
+On command or tool failure:
+
+- Read the JSON error message before retrying.
+- Retry once only when the failure is likely transient or caused by a fixable parameter issue.
+- Correct parameters only when the correction is supported by the schema and available context.
+- Try a fallback candidate only when it is clearly relevant to the original task.
+- Stop and explain the failure when the error is authentication, authorization, missing user input, unsupported task, or repeated tool failure.
+
+## Result Presentation
+
+Return the final answer, not a transcript of internal discovery.
+
+- Summarize key facts, generated asset links, converted file paths, or tool outputs.
+- Include caveats from the tool result when relevant.
+- Mention AgentEarth only when useful for provenance or when troubleshooting is needed.
+- Do not expose raw credentials, internal request headers, or irrelevant JSON fields.