@agentearth.ai/cli 0.1.0-beta.7 → 0.1.0-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/skills/agentearth/SKILL.md +21 -43
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentearth.ai/cli",
3
- "version": "0.1.0-beta.7",
3
+ "version": "0.1.0-beta.8",
4
4
  "description": "Agent-first CLI that helps AI agents discover, inspect, and execute AgentEarth tools from any shell.",
5
5
  "type": "module",
6
6
  "bin": {
package/skills/agentearth/SKILL.md CHANGED
@@ -32,13 +32,11 @@ permissions:
32
32
 
33
33
  # AgentEarth
34
34
 
35
- 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.
36
-
37
35
  ## Command Surface
38
36
 
39
- Prefer `ae` on Unix-like shells and `ae.cmd` in Windows PowerShell when the PowerShell shim is blocked by execution policy.
37
+ Prefer `ae` on Unix-like shells and `ae.cmd` in Windows PowerShell when the PowerShell shim is blocked by execution policy. The npm package is `@agentearth.ai/cli`.
40
38
 
41
- The npm package is `@agentearth.ai/cli`. If `ae` is unavailable or not on `PATH`, use the npm fallback with the same subcommand:
39
+ If `ae` is unavailable or not on `PATH`, use the npm fallback with the same subcommand:
42
40
 
43
41
  ```text
44
42
  npx --yes --package @agentearth.ai/cli@latest ae recommend "<task>"
@@ -54,7 +52,22 @@ Use these commands:
54
52
  - `ae execute <tool_name> @params.json` to run the selected tool with validated parameters.
55
53
  - `ae update` only when the user confirms they want to update the CLI.
56
54
 
57
- 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`.
55
+ 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`. Do not call AgentEarth HTTP APIs directly from this skill; use the CLI command surface.
56
+
57
+ ## Workflow
58
+
59
+ 1. Build a concise query from the latest user request plus only necessary conversation context.
60
+ 2. For natural-language tasks, start with one `ae recommend "<task>"` call; use `ae list @query.json` only when the category or keyword is already clear.
61
+ 3. Select the most relevant candidate whose schema can be filled from available context, then inspect only that candidate with `ae detail <tool_name>`.
62
+ 4. Build `params.json` strictly from the inspected input schema.
63
+ 5. Validate required fields, types, enums, formats, and `additionalProperties` when present.
64
+ 6. Execute with `ae execute <tool_name> @params.json`.
65
+ 7. Summarize the useful result for the user and omit internal command noise unless troubleshooting needs it.
66
+
67
+ - Do not inspect environment variables, npm state, or installation paths before the first CLI attempt; trust CLI errors such as `auth_missing`, `auth_invalid`, or command-not-found.
68
+ - Use `ae` or `ae.cmd` first. Use the npx fallback only when the CLI command is unavailable.
69
+ - Do not inspect every recommended tool unless the selected candidate is unsuitable.
70
+ - If no candidate is suitable, refine the query once. If discovery still fails, tell the user that AgentEarth did not return a suitable tool.
58
71
 
59
72
  ## Credential Handling
60
73
 
@@ -71,32 +84,6 @@ Use credentials only through the active host environment.
71
84
 
72
85
  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.
73
86
 
74
- ## Execution Workflow
75
-
76
- 1. Restate the task internally as a concise AgentEarth query.
77
- 2. Discover candidate tools with `ae recommend "<task>"`, or `ae list @query.json` when the category is already clear.
78
- 3. Inspect the best candidate with `ae detail <tool_name>`.
79
- 4. Build `params.json` strictly from the inspected input schema.
80
- 5. Validate required fields, types, enums, formats, and `additionalProperties` when present.
81
- 6. Execute with `ae execute <tool_name> @params.json`.
82
- 7. Summarize the useful result for the user and omit internal command noise unless it is needed for troubleshooting.
83
-
84
- Use a fallback tool only when the first suitable tool fails for a recoverable reason or clearly does not satisfy the task.
85
-
86
- ## Tool Selection
87
-
88
- Choose the tool that best matches the task intent and can be safely executed with available context.
89
-
90
- Prefer candidates with:
91
-
92
- - clear task relevance;
93
- - complete and understandable input schema;
94
- - required parameters that can be filled from the user's request or conversation context;
95
- - lower cost when otherwise equivalent;
96
- - narrower, more specialized behavior for the requested job.
97
-
98
- If no candidate is suitable, refine the query once. If discovery still fails, tell the user that AgentEarth did not return a suitable tool.
99
-
100
87
  ## Parameter Rules
101
88
 
102
89
  Build parameter files as JSON objects matching the selected tool schema.
@@ -108,7 +95,7 @@ Build parameter files as JSON objects matching the selected tool schema.
108
95
  - Do not reuse example keys unless they exist in the selected schema.
109
96
  - Write query or execution payloads to JSON files instead of hand-writing inline JSON in PowerShell.
110
97
 
111
- Known-category list example:
98
+ Examples:
112
99
 
113
100
  ```json
114
101
  {"keyword":"image"}
@@ -118,30 +105,21 @@ Known-category list example:
118
105
  ae list @query.json
119
106
  ae detail <tool_name>
120
107
  ae execute <tool_name> @params.json
121
- ```
122
-
123
- Ambiguous-task example:
124
-
125
- ```text
126
108
  ae recommend "find current hotel prices in Sapporo for next weekend"
127
109
  ae detail <tool_name>
128
110
  ae execute <tool_name> @params.json
129
111
  ```
130
112
 
131
- ## Error Handling
113
+ ## Failure And Output
132
114
 
133
115
  On command or tool failure:
134
116
 
135
117
  - Read the JSON error message before retrying.
136
118
  - Retry once only when the failure is likely transient or caused by a fixable parameter issue.
137
119
  - Correct parameters only when the correction is supported by the schema and available context.
138
- - Try a fallback candidate only when it is clearly relevant to the original task.
120
+ - Try a fallback candidate only when it is clearly relevant to the original task and the first suitable tool fails for a recoverable reason or clearly does not satisfy the task.
139
121
  - Stop and explain the failure when the error is authentication, authorization, missing user input, unsupported task, or repeated tool failure.
140
122
 
141
- ## Result Presentation
142
-
143
- Return the final answer, not a transcript of internal discovery.
144
-
145
123
  - Summarize key facts, generated asset links, converted file paths, or tool outputs.
146
124
  - Include caveats from the tool result when relevant.
147
125
  - Mention AgentEarth only when useful for provenance or when troubleshooting is needed.