From 2c75e245c4409c46b737e578780d5b4c45c0f793 Mon Sep 17 00:00:00 2001 From: Kevin Cui Date: Thu, 24 Sep 2026 02:35:07 -0400 Subject: [PATCH] docs(skills): remove dated prompt patterns from bundled skills A prompt audit of the bundled skills turned up instructions that outlived their context. The publish skill told OpenClaw and QoderWork to swap their host id using a "supported list" that disappeared when the skills moved to per-agent templates, the find-skills skill repeated its keyword rule five times and carried circular tie-break coaching and a hardcoded "four options" that is wrong when only two exist, and _llm-client.md_ taught a hand-rolled JSON prompt, parse, and retry loop that `oo llm json` already provides. This removes the dead instructions, states each rule once, points structured output at `oo llm json`, aligns the description guidance in _oo-powered.md_ with _skill-authoring.md_, and adds the `bun run knip` step that _AGENTS.md_ was missing relative to _CLAUDE.md_. Signed-off-by: Kevin Cui --- AGENTS.md | 2 +- .../oo-create-skill/references/oo-powered.md | 24 ++++++------------ contrib/skills/shared/oo-find-skills/SKILL.md | 25 +++---------------- .../references/oo-cli-contract.md | 8 +----- .../skills/shared/oo-publish-skill/SKILL.md | 5 ---- .../skills/shared/oo/references/llm-client.md | 17 +++++++------ .../oo/references/search-and-selection.md | 2 +- .../commands/skills/embedded-assets.test.ts | 3 ++- 8 files changed, 25 insertions(+), 61 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 44dc6f8e..fe4ea7b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ ## Development Standards -- After each code modification, you must execute: `bun run lint:fix` `bun run ts-check` +- After each code modification, you must execute: `bun run lint:fix` `bun run ts-check` `bun run knip` - For any change that affects commands or CLI behavior, you must check whether documentation under `docs/` needs to be updated and update it when necessary - Documentation under `docs/commands*.md` should describe the user-facing CLI contract only: command purpose, arguments, options, stable output shapes, and externally observable behavior. Do not document internal implementation details such as validator order, AJV usage, schema patching, or other internal lint mechanics unless the user explicitly asks for that level of detail. - Comments must be in English diff --git a/contrib/skills/shared/oo-create-skill/references/oo-powered.md b/contrib/skills/shared/oo-create-skill/references/oo-powered.md index 3b944b46..fe38b001 100644 --- a/contrib/skills/shared/oo-create-skill/references/oo-powered.md +++ b/contrib/skills/shared/oo-create-skill/references/oo-powered.md @@ -294,22 +294,10 @@ skill directory already exists, use `oo skills adopt` only when it is the existing workflow the user wants to solidify; otherwise ask for a different skill name instead of overwriting. -Make `--description` a user-facing trigger summary: it becomes the frontmatter -description and the main signal future agents see before loading the skill. -Start with the user outcome. Include natural request verbs, domain nouns, -important input artifacts, expected outputs, and user-visible product, model, -service, or workflow names that improve matching. - -Prefer one or two concise sentences over a generic label. The description -should answer what the skill does and what users would ask. Keep operational -details, routing caveats, identifiers, schema details, command syntax, and -negative conditions in the workflow body unless they are natural user-facing -terms. - -Use this description shape when helpful: -`. Use when the user asks to for , especially when they need -.` +Write `--description` as the trigger contract described in +`skill-authoring.md`: it becomes the frontmatter description and the main +signal future agents see before loading the skill. Also name the user-visible +product, model, service, or workflow names that improve matching. Use the path printed by `oo skills init` or `oo skills adopt` as the skill directory for authoring and validation. @@ -398,7 +386,9 @@ directly, use that schema-driven input shape and do not add an unnecessary When generated skill code needs an OOMOL-hosted LLM client, instruct future agents to run `oo llm config --json` at runtime and use the returned `apiKey`, -`baseUrl`, and `model`. Do not hardcode, persist, log, or print the API key, +`baseUrl`, and `model`. When the runtime only needs schema-valid JSON from the +hosted LLM, use `oo llm json` instead of a hand-written JSON prompt, parser, and +retry loop. Do not hardcode, persist, log, or print the API key, and do not tell future agents to read local auth files directly. Before validation, re-check the trigger description and presentation metadata diff --git a/contrib/skills/shared/oo-find-skills/SKILL.md b/contrib/skills/shared/oo-find-skills/SKILL.md index 66f14e03..15798c90 100644 --- a/contrib/skills/shared/oo-find-skills/SKILL.md +++ b/contrib/skills/shared/oo-find-skills/SKILL.md @@ -30,8 +30,6 @@ Convert the user request into: Rules: - The sentence must always be in English, regardless of the user's language. -- Keywords are required on every search. Always provide `1` to `3` keywords and - never run a search without `--keywords`. - Keywords may use the user's original language. Keep product names, brand names, and proper nouns exactly as the user wrote them and do not translate them. For example, keep `滴答清单` as `滴答清单`; do not turn it into @@ -44,8 +42,6 @@ Rules: - Prefer a short sentence built from task + capability + domain or constraint. - Do not add meta words such as `skill`, `skills`, `search`, or `install` unless the user's actual need depends on those words. -- Avoid filler words. -- Do not exceed `3` keywords. Examples: @@ -60,12 +56,9 @@ Examples: - Sentence: `write Markdown more effectively` Keywords: `Markdown`, `writing` -Use the sentence as the main search text and always pass the `1` to `3` -keywords through `--keywords`. - ### 2. Search for candidate skills -Always run the keyword-refined form: +Always pass the keywords through `--keywords`: ```bash oo skills search "" --keywords "" --json @@ -164,8 +157,6 @@ with one of the displayed numbers. - If the user chooses `Install neither`, declines installation, or the UI returns `None of the above`, do not install anything. Reply with exactly one short acknowledgement in the user's language that no skill was installed, then stop. - Do not continue with extra result explanation, matched-result recap, ranking - recap, package names, skill names, descriptions, or repeated summaries. - Batch by package: - If both selected skills come from the same package, install them with one command and multiple `-s` flags. @@ -215,20 +206,12 @@ oo skills install "" -s "" ## Behavior Notes -- `oo skills search --json` returns at most `5` results because that is the CLI - behavior for this command; do not try to enforce or emulate a different - limit in the skill text. +- `oo skills search --json` returns at most `5` results. - Use `skillDisplayName` when present, otherwise fall back to `name`. -- Prefer the closest semantic match for the primary skill. -- Break ranking ties deterministically by preferring the result whose - `description` or display text more directly matches the same user request. -- Prefer non-duplicate results over near-duplicates. -- If the semantic match is still tied, prefer the result with clearer install - identifiers (`packageName` plus `name`) and richer explanatory text. - You may compare response text fields against the original user request, but you must not use external metadata or guessed fields to break ties. - Treat a fallback as credible only when it is the next-best result that still plausibly solves the same user request, not merely a loosely related or duplicate-looking match. -- Do not install anything before the user explicitly chooses one of the four - options. +- Do not install anything before the user explicitly chooses one of the offered + install actions. diff --git a/contrib/skills/shared/oo-find-skills/references/oo-cli-contract.md b/contrib/skills/shared/oo-find-skills/references/oo-cli-contract.md index b2a551ec..a00c8eb9 100644 --- a/contrib/skills/shared/oo-find-skills/references/oo-cli-contract.md +++ b/contrib/skills/shared/oo-find-skills/references/oo-cli-contract.md @@ -85,11 +85,6 @@ Output shape: Ranking guidance: -- Prefer the installable result whose `description` or display text more - directly matches the same user request. -- Prefer non-duplicate results over near-duplicates. -- If the semantic match is tied, prefer the result with clearer install - identifiers (`packageName` plus `name`) and richer explanatory text. - You may compare response text fields against the original user request, but you must not use external metadata or guessed fields to break ties. @@ -101,8 +96,7 @@ Failure handling: succeeded, and do not continue silently. - If the user chooses `Install neither`, declines installation, or the UI returns `None of the above`, do not install anything. Reply with exactly one short - acknowledgement in the user's language that no skill was installed, then stop - without extra result recap, package names, skill names, or descriptions. + acknowledgement in the user's language that no skill was installed, then stop. - If any `oo` output shows HTTP `402` or `OOMOL_INSUFFICIENT_CREDIT`, stop immediately, tell the user their current account has insufficient credit or is overdue, and direct them to diff --git a/contrib/skills/shared/oo-publish-skill/SKILL.md b/contrib/skills/shared/oo-publish-skill/SKILL.md index 6d26edca..7f939bf5 100644 --- a/contrib/skills/shared/oo-publish-skill/SKILL.md +++ b/contrib/skills/shared/oo-publish-skill/SKILL.md @@ -83,11 +83,6 @@ oo skills publish /path/to/my-skill/SKILL.md --visibility private oo skills publish ./already-published-skill ``` - -If this shared skill file is running in another supported host, replace -`` with that host id from the supported list. - - If the command prompts about publishing a registry-installed skill under the active account or overwriting an existing remote package, let that prompt drive the next user confirmation. Do not ask those questions in advance. diff --git a/contrib/skills/shared/oo/references/llm-client.md b/contrib/skills/shared/oo/references/llm-client.md index 5ba5687d..c77d43c6 100644 --- a/contrib/skills/shared/oo/references/llm-client.md +++ b/contrib/skills/shared/oo/references/llm-client.md @@ -34,17 +34,18 @@ values into the client in memory. ## Structured JSON outputs -When using the hosted LLM for a local structured-output task: +When a local task needs structured JSON from the hosted LLM, run +`oo llm json --schema --input --json` instead of +prompting for JSON and parsing it yourself. The command requests JSON output, +validates it against the schema (root type `object`), retries invalid output +within `--max-retries`, and prints `{ ok, data, model, attempts }`. + +For batches: -- Ask for JSON only, with no Markdown fences or prose. -- Provide the exact object shape and required fields in the request. - Include stable item identifiers in each input item when the caller must reconcile batched outputs. -- Parse the model output as JSON before trusting it. -- Validate required keys, primitive types, and item identifiers locally. -- Save valid returned items before retrying failures. -- Retry only missing or invalid items when the task semantics allow partial - recovery. +- Save valid returned items before retrying failures, and retry only missing or + invalid items when the task semantics allow partial recovery. - Keep checkpoint files for long batches so an interrupted run can continue without repeating successful LLM work. diff --git a/contrib/skills/shared/oo/references/search-and-selection.md b/contrib/skills/shared/oo/references/search-and-selection.md index eb818ee3..78207618 100644 --- a/contrib/skills/shared/oo/references/search-and-selection.md +++ b/contrib/skills/shared/oo/references/search-and-selection.md @@ -30,7 +30,7 @@ Guidance: Make it explicit even when the user only implies it (for example "put it on my calendar" for a connected Google Calendar, or "delete that 3pm call" for a calendar event). -- But do NOT guess a provider you are unsure about. When the user's wording maps +- Do not guess a provider you are unsure about. When the user's wording maps to a generic capability that several providers offer, and nothing in the request or known connected accounts tells you which one the user uses (for example "my workbook" -> Excel or Google Sheets, "my deals" -> HubSpot or diff --git a/src/application/commands/skills/embedded-assets.test.ts b/src/application/commands/skills/embedded-assets.test.ts index 1cf8fba1..8765526b 100644 --- a/src/application/commands/skills/embedded-assets.test.ts +++ b/src/application/commands/skills/embedded-assets.test.ts @@ -928,7 +928,8 @@ describe("embedded skill assets", () => { expect(qoderWorkCreateOoContent).toContain("oo skills preflight --agent qoderwork"); expect(universalCreateContent).toContain("references/skill-authoring.md"); expect(qoderWorkCreateContent).toContain("references/oo-powered.md"); - expect(qoderWorkPublishContent).toContain("`qoderwork` with that host id"); + expect(qoderWorkPublishContent).toContain("oo skills locate --agent qoderwork"); + expect(qoderWorkPublishContent).not.toContain("supported list"); expect(qoderWorkPublishContent).not.toContain("agentic:"); });