From a23b71ecfcaa6b92730bf34f1898219b7e6feff7 Mon Sep 17 00:00:00 2001 From: Danil Silantyev Date: Sat, 18 Jul 2026 08:23:30 +0500 Subject: [PATCH] docs(skills): rewrite nddev-builder skill descriptions to trigger-first best practice Rework all 16 core skill descriptions to follow Anthropic's skill-authoring guidance: each is now a third-person capability statement plus concrete WHEN-to-use triggers, with the internal-coverage clause ("Covers/Creates/ Explains/Checks/Scans ...") removed. That clause summarized each skill's workflow, which (a) risks the model following the description instead of reading the skill body and (b) wastes always-preloaded metadata budget across all 16 descriptions. The cross-skill routing redirects for add-skill / add-command / add-agent are preserved so the routing-overlap validator still passes. Descriptions shrank from roughly 400-600 to 190-400 characters each; no component, command, agent, or runtime behavior changed. Refresh the release-evidence content digest to match the new blobs. Claude-Session: https://claude.ai/code/session_01Y29c9sJRhChvxDcUjab5Xo --- build/release-evidence.json | 8 ++++---- .../nddev-builder/plugins/core/skills/add-agent/SKILL.md | 2 +- .../plugins/core/skills/add-command/SKILL.md | 2 +- .../nddev-builder/plugins/core/skills/add-hook/SKILL.md | 2 +- .../plugins/core/skills/add-instructions/SKILL.md | 2 +- .../plugins/core/skills/add-marketplace/SKILL.md | 2 +- .../plugins/core/skills/add-mcp-server/SKILL.md | 2 +- .../nddev-builder/plugins/core/skills/add-plugin/SKILL.md | 2 +- .../plugins/core/skills/add-provider/SKILL.md | 2 +- .../plugins/core/skills/add-reference/SKILL.md | 2 +- .../nddev-builder/plugins/core/skills/add-skill/SKILL.md | 2 +- .../nddev-builder/plugins/core/skills/add-tool/SKILL.md | 2 +- .../plugins/core/skills/enable-plugin/SKILL.md | 2 +- .../plugins/core/skills/list-components/SKILL.md | 2 +- .../core/skills/nddev-builder-orientation/SKILL.md | 2 +- .../plugins/core/skills/remove-component/SKILL.md | 2 +- .../plugins/core/skills/validate-components/SKILL.md | 2 +- 17 files changed, 20 insertions(+), 20 deletions(-) diff --git a/build/release-evidence.json b/build/release-evidence.json index dd39000..d10deb3 100644 --- a/build/release-evidence.json +++ b/build/release-evidence.json @@ -2,11 +2,11 @@ "schema_version": 2, "module": { "repository": "NDDev-it-com/nddev-zcode-app", - "setup_digest": "sha256:bba623d9aa81f6934ebe77dd5a635fc3544b5304a211b021401c4568bdffb511" + "setup_digest": "sha256:0c6047fe00792d965c03bb3bdfc1cf12d93176fb8353c01ed9619ef3dd88339d" }, "harness": { "repository": "NDDev-it-com/nddev-harnesses", - "commit": "df99892732c0b9ebaa8906773ec8d36e1521d960" + "commit": "066428831895a58ab964d1aa07587430eba1061f" }, "adapter": { "id": "zcode", @@ -30,8 +30,8 @@ } ], "lanes": [], - "generated_at_utc": "2026-07-18T02:35:51Z", - "expires_at_utc": "2027-01-14T02:35:51Z", + "generated_at_utc": "2026-07-18T03:22:57Z", + "expires_at_utc": "2027-01-14T03:22:57Z", "promotion": { "decision": "pending", "waivers": [] diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md index fe05bca..1b398da 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md @@ -1,6 +1,6 @@ --- name: add-agent -description: Author a new ZCode subagent (agents/.md with name + model frontmatter) in the correct location inside the active marketplace. Covers role definition, model pinning, and output contracts. Use when adding a subagent (reviewer, researcher, worker) to the nddev-builder or any marketplace. +description: Authors a ZCode subagent as agents/.md in a marketplace. Use when adding, defining, or configuring a subagent — a reviewer, researcher, or worker the main agent can delegate to. For a slash command use add-command; for a SKILL.md use add-skill. --- # add-agent diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md index 3c2dfa4..fc65fe3 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md @@ -1,6 +1,6 @@ --- name: add-command -description: Author a new ZCode slash command (commands/.md with YAML frontmatter) in the correct location inside the active marketplace. Covers frontmatter requirements, naming, and nested-command colon syntax. Use when adding a new slash command to the nddev-builder or any marketplace. +description: Authors a ZCode slash command as commands/.md in a marketplace. Use when adding or defining a slash (/) command, including nested colon-separated commands. For a SKILL.md use add-skill; for a subagent use add-agent. --- # add-command diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md index 719f03e..bbc95fb 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md @@ -1,6 +1,6 @@ --- name: add-hook -description: Register a lifecycle hook in the active marketplace's hooks.json and wire its command script. Covers the seven ZCode hook events, the matcher + command shape, the hooks.enabled flag, and how the installer merges hooks into cli/config.json. Use when adding a SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, or Stop hook. +description: Registers a ZCode lifecycle hook in a marketplace's hooks.json. Use when adding or configuring a SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, or Stop hook, or wiring a hook matcher, command, or timeout. --- # add-hook diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md index 9e697e1..bb314ac 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md @@ -1,6 +1,6 @@ --- name: add-instructions -description: Author or maintain ZCode AGENTS.md instruction files at user or workspace scope. Use when adding default agent instructions, editing AGENTS.md, deciding user-vs-workspace scope, or understanding the load and merge order of instruction files in ZCode. +description: Authors and maintains ZCode AGENTS.md instruction files at user or workspace scope. Use when adding default agent instructions, editing AGENTS.md, deciding user-vs-workspace scope, or reasoning about the load and merge order of instruction files in ZCode. --- # Add or maintain AGENTS.md instructions diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md index c70d5c6..dfb142e 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md @@ -1,6 +1,6 @@ --- name: add-marketplace -description: Scaffold a new self-contained marketplace (a complete ~/.zcode setup) under zcode_tools/marketplaces/. Creates all required files (AGENTS.md, marketplace.json, config templates, mcp/hooks, empty skills/commands/agents/plugins dirs) so the installer's validation passes. Use when creating a brand-new setup like nddev-builder or nddev-designer. +description: Scaffolds a new self-contained ZCode marketplace — a complete ~/.zcode setup — under zcode_tools/marketplaces/. Use when creating a brand-new setup or profile such as nddev-builder or nddev-designer, or bootstrapping a marketplace directory from scratch. --- # add-marketplace diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md index 15f2be1..144b458 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md @@ -1,6 +1,6 @@ --- name: add-mcp-server -description: Register a tool integration for the agent — either a classic MCP server OR a CLI+skill alternative. Covers the MCP vs CLI trade-off (token cost, composability), both registration paths, and secrets handling. Use when adding any external tool, API, or data source the agent should be able to call. +description: Registers a tool integration for the agent — a classic MCP server or a lean CLI+skill alternative. Use when adding any external tool, API, or data source the agent should call, or choosing between an MCP server and a CLI tool. For a plain CLI tool use add-tool. --- # add-mcp-server diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-plugin/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-plugin/SKILL.md index aaf3173..8217248 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-plugin/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-plugin/SKILL.md @@ -1,6 +1,6 @@ --- name: add-plugin -description: Scaffold a new self-contained ZCode plugin bundle inside a marketplace. Creates the .zcode-plugin/plugin.json manifest (metadata-only), the convention directories (skills/, commands/, agents/), a README, and registers the plugin in that marketplace's marketplace.json. Use when adding a new plugin to any nddev marketplace. +description: Scaffolds a new self-contained plugin bundle inside a ZCode marketplace and registers it in marketplace.json. Use when adding a plugin to a marketplace, or grouping skills, commands, and agents into one installable bundle. --- # add-plugin diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-provider/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-provider/SKILL.md index 68ef755..554fd4b 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-provider/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-provider/SKILL.md @@ -1,6 +1,6 @@ --- name: add-provider -description: Add a model provider to a marketplace's v2-config template. Covers the provider shape (name, kind, options.apiKey, options.baseURL, enabled, source, models), secret placeholder handling, and both anthropic and openai-style providers. Use when adding a new LLM provider (e.g. OpenAI, Anthropic, a custom endpoint) to a ZCode setup. +description: Adds a model provider to a marketplace's config template. Use when adding or configuring an LLM provider — OpenAI, Anthropic, or a custom OpenAI-compatible endpoint — or wiring provider models, base URL, or API-key placeholders into a ZCode setup. --- # add-provider diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-reference/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-reference/SKILL.md index 378bd58..ff82065 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-reference/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-reference/SKILL.md @@ -1,6 +1,6 @@ --- name: add-reference -description: Add a reference documentation file to a plugin bundle. Reference docs live under plugins//references/ and are Markdown files that provide context the agent reads alongside skills and commands. Not a component type — just documentation. Use when adding a spec, format reference, or design doc that plugin skills and commands should be able to cite. +description: Adds a reference documentation file — a spec, format reference, or design doc — under a plugin's references/ directory. Use when adding background documentation that plugin skills and commands should cite. Reference docs are plain Markdown, not a loadable component type. --- # add-reference diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-skill/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-skill/SKILL.md index a292947..3db28c2 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-skill/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: add-skill -description: Author a new ZCode skill (SKILL.md with YAML frontmatter) in the correct location — either inside a plugin bundle or at user scope. Covers frontmatter requirements, discovery order, and naming. Use when adding a skill to the nddev-zcode-app setup; use add-command for a slash command and add-agent for a subagent. +description: Authors a ZCode skill (SKILL.md) inside a plugin bundle or at user scope. Use when adding a skill or teaching the agent a reusable workflow. For a slash command use add-command; for a subagent use add-agent. --- # add-skill diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-tool/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-tool/SKILL.md index a6425ea..f19d118 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-tool/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-tool/SKILL.md @@ -1,6 +1,6 @@ --- name: add-tool -description: Add a CLI tool (non-MCP) to a plugin bundle. Creates a tools directory with an executable script and a README, plus optionally a companion skill that teaches the agent how to invoke the tool. Covers the CLI+skill pattern as a small-baseline, on-demand alternative to MCP servers that is more composable but less constrained. Use when adding a linter, formatter, utility script, or any command-line tool the agent should be able to run. +description: Adds a CLI tool — a non-MCP executable script plus an optional companion skill — to a plugin bundle. Use when adding a linter, formatter, utility script, or any command-line tool the agent should run. For a classic MCP server use add-mcp-server. --- # add-tool diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/enable-plugin/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/enable-plugin/SKILL.md index 3e77742..3d8ac3d 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/enable-plugin/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/enable-plugin/SKILL.md @@ -1,6 +1,6 @@ --- name: enable-plugin -description: Enable or disable a plugin in a marketplace's cli-config template by populating the enabledPlugins map. Explains the plugin enable key format (name@marketplace) and the enabled/disabled semantics. Use when a marketplace has plugins registered in marketplace.json but they are not enabled in the config template, or when you need to toggle a plugin on or off. +description: Enables or disables a registered plugin in a marketplace's config template. Use when a plugin is registered in marketplace.json but not active, or when toggling a plugin on or off for a setup. --- # enable-plugin diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/list-components/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/list-components/SKILL.md index 53d6a51..f748b40 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/list-components/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/list-components/SKILL.md @@ -1,6 +1,6 @@ --- name: list-components -description: List all plugins, skills, commands, agents, hooks, and MCP servers in a marketplace. Scans the directory tree and reads marketplace.json to report counts and paths. Read-only — no file changes. Use when you need to see what a marketplace contains, inspect its structure, or check what components exist before adding or removing one. +description: Lists the plugins, skills, commands, agents, hooks, and MCP servers in a marketplace. Read-only — makes no changes. Use when inspecting what a marketplace contains, or checking existing components before adding or removing one. --- # list-components diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md index 6cfa034..5b6207d 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md @@ -1,6 +1,6 @@ --- name: nddev-builder-orientation -description: Orient in the nddev-builder toolkit and in how ZCode 3.3.6 actually discovers and loads extensions. Use when asking how nddev-builder is structured, how ZCode loads skills/commands/agents, where components go and why, why an installed skill is not loading, what the installer does (flatten to user scope), or the install/remove/switch lifecycle. Read this first before authoring or debugging a marketplace. +description: Orients you in the nddev-builder toolkit and in how ZCode 3.3.6 discovers and loads extensions. Use when asking how nddev-builder is structured, how ZCode loads skills/commands/agents, where components go and why, why an installed skill is not loading, what the installer does (flatten to user scope), or the install/remove/switch lifecycle. Read this first before authoring or debugging a marketplace. --- # nddev-builder orientation diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/remove-component/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/remove-component/SKILL.md index 0428ae0..235a298 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/remove-component/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/remove-component/SKILL.md @@ -1,6 +1,6 @@ --- name: remove-component -description: Safely remove a component (plugin, skill, command, agent, reference, or CLI tool) from a marketplace. Checks for references in other files before deletion, updates marketplace.json if removing a plugin, and validates JSON after changes. Refuses if the component is referenced elsewhere unless the user confirms. Use when cleaning up, refactoring, or deleting a component that is no longer needed. +description: Removes a component — a plugin, skill, command, agent, reference, or CLI tool — from a marketplace safely, refusing when it is still referenced elsewhere. Use when cleaning up, refactoring, or deleting a component that is no longer needed. --- # remove-component diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/validate-components/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/validate-components/SKILL.md index 29b7cbe..0dac284 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/validate-components/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/validate-components/SKILL.md @@ -1,6 +1,6 @@ --- name: validate-components -description: Statically pre-check a marketplace's components before install so an authoring mistake fails at author time, not install time. Use before installing or shipping a marketplace, or when a skill/command/agent is rejected — checks frontmatter, name patterns, description length, JSON validity, and the cross-plugin basename collision that makes the installer fail closed. +description: Validates a marketplace's components statically before install, so an authoring mistake fails at author time instead of install time. Use before installing or shipping a marketplace, or when a skill, command, or agent is being rejected or silently dropped. --- # Validate marketplace components