CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

tool-design

设计 Agent 工具时使用——新增/重构工具集、给 MCP 服务器设计工具、判断能力该做成专用工具还是 Skill、编写工具描述与参数 schema、设计感知工具的输出分页与截断、给执行工具加安全审批与沙盒、设计子 Agent 协作接口时查阅。覆盖工具分类、ACI 通用设计原则、感知/执行/协作三类工具的设计要点。

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a dense, highly actionable design reference with concrete thresholds, templates, examples, and error-recovery patterns — close to ideal for an instruction-only skill. Its main weaknesses are moderate verbosity in rationale narration and a progressive-disclosure failure: the referenced companion code and reading files are absent from the bundle, leaving dangling pointers.

Suggestions

Progressive disclosure: either ship the referenced `chapter4/*` MCP servers and `book/chapter4.md` inside the skill bundle (e.g., under references/ or scripts/) or remove/rewrite the 配套代码 and 深度阅读 sections so every path resolves.

Conciseness: compress the narrative justifications (e.g., the 专用工具 four-condition list and the three multimodal-path comparison) into bare rules or a table, trimming the rationale prose that a capable model can infer.

Workflow clarity: add a short decision procedure at the top (e.g., classify the capability → check the form-selection table → jump to the relevant 实践模式 subsection) so the six practice patterns read as one navigable workflow rather than parallel sections.

DimensionReasoningScore

Conciseness

The body is dense and prescriptive — it assumes competence (no explanation of what an API or LLM is) and every section carries non-obvious rules, thresholds, and war stories (Cursor quote-mangling, the git-commit tag injection). It is not score 5 because some narrative explanation (e.g., the four-condition justification in 核心原则 and the multimodal-path comparisons) could be tightened into bare rules, and at ~97 dense lines a few passages over-explain their rationale.

4 / 5

Actionability

For an instruction-only design skill the guidance is copy-paste concrete: exact truncation templates ('已显示第 1-200 行,共 5000 行,可用 offset 继续读取', head 50 + tail 50 lines with a '[省略 8523 行…]' marker), example parameter formats (RFC3339 '2024-03-15T14:30:00Z', E.164 '+8613888888888'), a form-selection decision table, named tool patterns (`read_document(file_type=...)`, `get_page_metadata`, `spawn_subagent`), and concrete run commands (`python cli.py demo`). Specific examples cover the common design cases, matching the score-5 anchor; per the rubric's code_vs_instruction note, the absence of code blocks is not penalized since the guidance is directly actionable.

5 / 5

Workflow Clarity

Mini-workflows are clearly sequenced with explicit checkpoints and error-recovery loops: the execution-safety pipeline '输入验证 → 权限控制 → 提议者-审核者 → Sidecar', the debugging rule 'Agent 频繁选错工具时,先查工具描述', and feedback loops like '审批失败要把拒绝理由…加入轨迹,而不是简单重试' and the Sidecar '拒绝熔断器'. It falls short of score 5 because the skill is a reference guide with no single end-to-end decision procedure (e.g., 'first classify the tool, then apply §X') tying the six practice patterns into one navigable sequence.

4 / 5

Progressive Disclosure

Inline structure is good (clear sections: 何时使用 / 核心原则 / 实践模式 / 常见陷阱 / 配套代码 / 深度阅读), but the bundle contains no files at all — the '配套代码' paths (`chapter4/perception-tools/`, `chapter4/execution-tools/`, `chapter4/collaboration-tools/`, `chapter4/multimodal-agent/`) and '深度阅读' path (`book/chapter4.md`) do not exist in the skill directory, so the references are dangling. This matches the score-3 anchor (references present but not effectively usable / organization could be better) rather than score 4, since navigation to the referenced material is broken.

3 / 5

Total

16

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An exemplary description: it pairs an explicit use-when clause enumerating seven concrete trigger situations with a crisp statement of what the skill covers, all in third-person imperative voice with no filler. The only weakness is modest synonym coverage (e.g., 'function calling', 'tool use') in the trigger terms.

DimensionReasoningScore

Specificity

The description enumerates multiple concrete capabilities — '新增/重构工具集、给 MCP 服务器设计工具、判断能力该做成专用工具还是 Skill、编写工具描述与参数 schema、设计感知工具的输出分页与截断、给执行工具加安全审批与沙盒、设计子 Agent 协作接口' — and summarizes scope ('覆盖工具分类、ACI 通用设计原则、感知/执行/协作三类工具的设计要点'). This matches the anchor 'lists multiple specific concrete actions; comprehensive coverage'; it is not score 4 because coverage of the domain is comprehensive rather than having minor gaps.

5 / 5

Completeness

Both halves are explicit: 'when' via the opening use-when clause '设计 Agent 工具时使用——……设计子 Agent 协作接口时查阅' with seven concrete trigger situations, and 'what' via '覆盖工具分类、ACI 通用设计原则、感知/执行/协作三类工具的设计要点'. This clearly matches the score-5 anchor (explicit what AND when with concrete trigger phrases) rather than the score-4 anchor where the 'when' could be more specific.

5 / 5

Trigger Term Quality

Natural trigger phrases users would say are well covered: 'Agent 工具', 'MCP 服务器', '工具描述', '参数 schema', '沙盒', '审批', '分页', '子 Agent'. It falls short of the score-5 anchor because common synonyms such as 'function calling' or 'tool use' (which the body itself uses) are absent from the description, leaving a few natural terms missing.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — designing agent-facing tools (ACI) — with distinctive triggers like '判断能力该做成专用工具还是 Skill' and '设计感知工具的输出分页与截断' that few other skills would claim. Minor overlap with a hypothetical skill-authoring guide exists ('还是 Skill'), but it is small enough that the score-5 anchor ('clear niche with distinct triggers; minimal conflict risk') fits better than score 4.

5 / 5

Total

19

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

bojieli/ai-agent-book

Path

skills/tool-design/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.