@standardagents/skill 0.45.1 → 0.45.3
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.
- package/README.md +17 -14
- package/package.json +1 -1
- package/skills/agentbuilder/SKILL.md +40 -14
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @standardagents/skill
|
|
2
2
|
|
|
3
|
-
Markdown-authored coding skills for Standard Agents
|
|
3
|
+
Markdown-authored coding skills for Standard Agents Builder.
|
|
4
4
|
|
|
5
5
|
## Overview
|
|
6
6
|
|
|
@@ -29,20 +29,23 @@ Recommended:
|
|
|
29
29
|
npx @standardagents/cli skill
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
This opens an interactive picker and installs the bundled `agentbuilder`
|
|
33
|
-
|
|
32
|
+
This opens an interactive picker and installs the bundled `agentbuilder` skill
|
|
33
|
+
as an [Agent Skills](https://agentskills.io) folder. Every target gets the same
|
|
34
|
+
`agentbuilder/SKILL.md`:
|
|
34
35
|
|
|
35
|
-
- Codex
|
|
36
|
-
|
|
36
|
+
- Codex and other coding agents (Cursor, Gemini CLI, GitHub Copilot, OpenCode,
|
|
37
|
+
and others) read it from `~/.agents/skills`
|
|
38
|
+
- Claude Code reads it from `~/.claude/skills`
|
|
37
39
|
|
|
38
|
-
|
|
40
|
+
Without a terminal the command installs into `~/.agents/skills`. Use
|
|
41
|
+
`--agent agents` or `--agent claude` to skip the picker, and `--dir` for an
|
|
42
|
+
agent that reads skills from another directory, or for a project-level
|
|
43
|
+
install such as `.agents/skills`.
|
|
39
44
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
The `agentbuilder` skill defers to `spec` for what the specification requires,
|
|
45
|
-
and it reads the published specification directly when `spec` is not installed.
|
|
45
|
+
There is one skill. The Standard Agent Specification is documentation, and the
|
|
46
|
+
`agentbuilder` skill tells the coding agent to read
|
|
47
|
+
`https://standardagentspec.org/llms.txt` and the pages it lists. When the skill
|
|
48
|
+
and the published specification disagree, the specification is correct.
|
|
46
49
|
|
|
47
50
|
Package install:
|
|
48
51
|
|
|
@@ -69,13 +72,13 @@ Copy the editable markdown skill into a local skills directory:
|
|
|
69
72
|
```ts
|
|
70
73
|
import { copySkill } from '@standardagents/skill'
|
|
71
74
|
|
|
72
|
-
await copySkill('agentbuilder', '.
|
|
75
|
+
await copySkill('agentbuilder', '.agents/skills', { overwrite: true })
|
|
73
76
|
```
|
|
74
77
|
|
|
75
78
|
That creates:
|
|
76
79
|
|
|
77
80
|
```text
|
|
78
|
-
.
|
|
81
|
+
.agents/skills/
|
|
79
82
|
agentbuilder/
|
|
80
83
|
SKILL.md
|
|
81
84
|
```
|
package/package.json
CHANGED
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
name: agentbuilder
|
|
3
3
|
description: >
|
|
4
4
|
Use this skill when creating, editing, debugging, reviewing, or documenting
|
|
5
|
-
Standard Agents
|
|
5
|
+
Standard Agents Builder projects. Apply it for work on agents,
|
|
6
6
|
prompts, models, tools, hooks, threads, APIs, subagents, provider setup,
|
|
7
7
|
model selection, environment variables, and spec-aligned architecture, even
|
|
8
8
|
if the user only says things like "build an agent", "write a prompt",
|
|
9
|
-
"choose a model", or "fix my
|
|
9
|
+
"choose a model", or "fix my Standard Agents Builder app" without explicitly naming
|
|
10
10
|
Standard Agents.
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
#
|
|
13
|
+
# Standard Agents Builder Skill
|
|
14
14
|
|
|
15
15
|
This guide is a living record. It is not part of the Standard Agent Specification — it exists to help humans and coding agents *use* the spec to build effective agents. It is updated regularly and not bound to any spec version.
|
|
16
16
|
|
|
@@ -32,11 +32,15 @@ For deeper reference material that this skill links to, see:
|
|
|
32
32
|
|
|
33
33
|
## The specification comes first
|
|
34
34
|
|
|
35
|
-
This skill covers how to build with
|
|
35
|
+
This skill covers how to build with Standard Agents Builder. The published Standard Agent Specification defines what a Standard Agent is. Read it before you answer what the specification requires, decide whether an agent is portable, or write or review a definition that must conform. Do not answer from memory, and do not rely on a remembered version number.
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
1. Read https://standardagentspec.org/llms.txt. Its `Latest version:` line names the latest version, and it lists a Markdown URL for every page of that version.
|
|
38
|
+
2. Use the latest version unless the user or the project names another one. For a named older version, read `https://standardagentspec.org/api/navigation/<version>.json`. Each `href` in it becomes a Markdown URL when you put `https://standardagentspec.org` before it and `.md` after it.
|
|
39
|
+
3. Read every page that governs the question, and follow links to the pages it depends on. Build URLs only from the index or the navigation file. Treat a response as not found unless its content type is `text/markdown`, or `text/plain` for `llms.txt`, because the site can answer an unknown path with an HTML page and status 200.
|
|
40
|
+
4. Name the version and the pages you used in your answer. Separate what the specification requires from what it recommends and from your own inference. When the specification does not define something, say so.
|
|
41
|
+
5. If you cannot reach the site, tell the user, and label anything you then say about the specification as unverified.
|
|
42
|
+
|
|
43
|
+
If this skill and the published specification disagree, the specification is correct. Report the disagreement to the user. Standard Agents Builder's types, source, and documentation, and this skill, describe Standard Agents Builder only.
|
|
40
44
|
|
|
41
45
|
## Keeping this skill up to date
|
|
42
46
|
|
|
@@ -47,8 +51,8 @@ This skill ships as `@standardagents/skill` on npm, and the version installed he
|
|
|
47
51
|
1. If the stamp above still reads `__SKILL_VERSION__`, this is an unstamped development copy — skip this check.
|
|
48
52
|
2. Run `npm view @standardagents/skill version`. If the command fails (offline, no npm, no shell access), skip silently. This check must never block, retry, or interrupt real work.
|
|
49
53
|
3. If the published version is newer than the stamp, tell the user in one short line and offer to update. Updating overwrites this file — including any local edits — so get the user's OK before running:
|
|
50
|
-
-
|
|
51
|
-
-
|
|
54
|
+
- Claude Code install (file lives under `.claude/skills/`): `npx @standardagents/cli@latest skill --force --agent claude`
|
|
55
|
+
- Any other install (file lives under `.agents/skills/`, or under `.codex/skills/` from an earlier release): `npx @standardagents/cli@latest skill --force --agent agents`
|
|
52
56
|
4. After updating, re-read the new file before continuing.
|
|
53
57
|
|
|
54
58
|
Do this at most once per conversation, then move on to the task at hand.
|
|
@@ -63,7 +67,7 @@ Most failed Standard Agent projects fail in the same seven ways. Read this secti
|
|
|
63
67
|
List the domains the system touches. Determine the tree (coordinator → domain agents → sub-domain agents). *Then* decide what each node is. Do not start by writing one agent and bolting tools onto it. → [Architecture & decomposition](#architecture--decomposition)
|
|
64
68
|
|
|
65
69
|
**2. Decide what backs each side. Prompt × prompt is the default worker shape; a human backing is the exception.**
|
|
66
|
-
Every agent has exactly two explicit sides, and each side is backed by exactly one of a human, a prompt, or a handler. A human backing is correct only when the thread itself is the chat surface (chat UI, website widget,
|
|
70
|
+
Every agent has exactly two explicit sides, and each side is backed by exactly one of a human, a prompt, or a handler. A human backing is correct only when the thread itself is the chat surface (chat UI, website widget, Standard Agents Builder admin, direct API chat). For Slack, email, SMS, Discord, webhooks, polled inboxes, schedulers, or any other mediated channel, the human is just a tool target — back both sides with prompts. The whole graph being prompt × prompt is fine and often cleaner. → [What backs each side?](#what-backs-each-side)
|
|
67
71
|
|
|
68
72
|
**3. Every prompt × prompt agent must have explicit session boundaries.**
|
|
69
73
|
Name its `sessionStop` tool. Name its `sessionFail` tool. Set a finite `maxSessionTurns` (the spec makes the cap optional; this skill makes it required practice for prompt × prompt). Give side B a real, non-redundant job. If you cannot say in one sentence what tool call ends the session, the agent is not designed yet. → [Session boundary discipline](#session-boundary-discipline)
|
|
@@ -204,7 +208,7 @@ Every agent has **exactly two sides** — `sideA` and `sideB` — and each side
|
|
|
204
208
|
|
|
205
209
|
There is no agent `type` field. Chat surface, composability, and termination are all **derived from the backings**. Both sides are always explicit — if a person takes side B's turns, write `sideB: { human: true }`; there is no implicit default side.
|
|
206
210
|
|
|
207
|
-
> **Prompt × prompt is the default worker shape. A human backing is the exception**, used only when the thread itself is the chat surface — chat UI, website widget,
|
|
211
|
+
> **Prompt × prompt is the default worker shape. A human backing is the exception**, used only when the thread itself is the chat surface — chat UI, website widget, Standard Agents Builder admin, or an API the user is talking to directly.
|
|
208
212
|
|
|
209
213
|
For **Slack, email, SMS, Discord, webhooks, polled inboxes, schedulers, or any other mediated channel**, the human is just a tool target. Back both sides with prompts. The whole graph being prompt × prompt is fine — often cleaner.
|
|
210
214
|
|
|
@@ -567,7 +571,7 @@ probabilities, confidence, and score legends; boolean answers return a 0–1
|
|
|
567
571
|
request/response/duration/status/cost automatically, persist before the first
|
|
568
572
|
message, and never append messages;
|
|
569
573
|
explicitly use `state.injectMessage()` when needed.
|
|
570
|
-
Automatic logging and optional `name`/`trigger` attribution are
|
|
574
|
+
Automatic logging and optional `name`/`trigger` attribution are Standard Agents Builder
|
|
571
575
|
extensions, not spec requirements. Standalone `typesafe({ apiKey }).decide(...)`
|
|
572
576
|
creates no thread logs. Read the package README for limits and the complete
|
|
573
577
|
conversion contract.
|
|
@@ -837,6 +841,28 @@ Common failure modes:
|
|
|
837
841
|
|
|
838
842
|
A prompt is what actually gets sent to the LLM at one step. Set on each prompt file in `agents/prompts/`. For full signatures, read the spec types from `node_modules/@standardagents/spec/dist/` (or browse `packages/spec/src/` on GitHub), and see `agents/prompts/AGENTS.md`.
|
|
839
843
|
|
|
844
|
+
Set `includePastTools` on every prompt that has tools to record the choice.
|
|
845
|
+
This includes callable tools, provider tools, and visible subagent lifecycle tools.
|
|
846
|
+
The specification defaults the flag to `false`.
|
|
847
|
+
With `false`, each request omits assistant tool calls and tool results from the running turn.
|
|
848
|
+
`includeChat: true` alone does not include tool history.
|
|
849
|
+
|
|
850
|
+
Choose `true` when a later step must read a tool result:
|
|
851
|
+
|
|
852
|
+
- The prompt answers from a tool result.
|
|
853
|
+
- A chained call uses an earlier result as input.
|
|
854
|
+
- The prompt answers from a blocking subagent result.
|
|
855
|
+
|
|
856
|
+
Choose `false` when the objective does not need earlier results in the request:
|
|
857
|
+
|
|
858
|
+
- The side ends its turn at the tool call.
|
|
859
|
+
- The tools only cause side effects.
|
|
860
|
+
- Results reach the model through another path, such as a hook summary or a subagent result message.
|
|
861
|
+
- Large or sensitive output must stay out of later requests.
|
|
862
|
+
|
|
863
|
+
A prompt that loops on tools with `false` may repeat calls until `maxSteps`.
|
|
864
|
+
Each prompt owns its flag.
|
|
865
|
+
|
|
840
866
|
```
|
|
841
867
|
PromptDefinition
|
|
842
868
|
name string unique snake_case identifier
|
|
@@ -844,7 +870,7 @@ PromptDefinition
|
|
|
844
870
|
prompt string | PromptContent[] system prompt (string, or composable parts)
|
|
845
871
|
model ModelName references agents/models/<name>
|
|
846
872
|
includeChat boolean (default false) pass full chat history to this LLM step
|
|
847
|
-
includePastTools boolean (default false)
|
|
873
|
+
includePastTools boolean (default false) include tool calls and results in later requests
|
|
848
874
|
parallelToolCalls boolean (default false) allow multiple tool calls per turn
|
|
849
875
|
toolChoice 'auto' | 'none' | 'required' tool calling strategy (default 'auto')
|
|
850
876
|
requiredSchema ZodSchema validate args when called as a tool
|
|
@@ -1180,7 +1206,7 @@ Validation order:
|
|
|
1180
1206
|
2. Refresh Cloudflare types:
|
|
1181
1207
|
- use `pnpm cf-typegen` if that script exists
|
|
1182
1208
|
- otherwise run `npx wrangler types`
|
|
1183
|
-
3. Regenerate
|
|
1209
|
+
3. Regenerate Standard Agents Builder types by running the project's build command:
|
|
1184
1210
|
- usually `pnpm build`, `npm run build`, `pnpm run dev`, or equivalent
|
|
1185
1211
|
4. Run the project's type checker:
|
|
1186
1212
|
- prefer `pnpm type-check` / `npm run type-check` if present
|