Skip to content

fix(tool/skill): cap description preview at 500 chars and load full S…#185

Merged
xiami762 merged 1 commit intomainfrom
fix/skill-description-progressive-load
Apr 24, 2026
Merged

fix(tool/skill): cap description preview at 500 chars and load full S…#185
xiami762 merged 1 commit intomainfrom
fix/skill-description-progressive-load

Conversation

@duguwanglong
Copy link
Copy Markdown
Contributor

The skill tool exposes two surfaces, both of which were silently dropping critical content:

  1. The tool's meta-description (shipped in every system prompt) listed each skill's full frontmatter description (up to 1024 chars). Long descriptions bloated the prompt and the model often acted on a partial preview without loading the full file.

  2. When the model called skill(name=...), ToolRegistry's auto-truncate path silently cropped the returned SKILL.md at 10 KB / 200 lines (head-only), dropping the workflow steps, references, and constraints that authors typically place at the end of the file. Users reported "skill.md 后面的 感觉就完全丢失了".

This change implements progressive disclosure (mirroring hermes-agent's skills_list / skill_view split):

  • build_description() now caps each skill's preview at MAX_SKILL_DESCRIPTION_PREVIEW_CHARS (500) using head + tail truncation, preserving both the opening (scope/triggers) and the closing (hard constraints like "必须先加载本 skill"). Adds an explicit instruction telling the model the previews are summaries and it MUST call skill(name=...) to load the full SKILL.md before acting.

  • skill_tool_impl() sets truncated=True on its ToolResult to opt out of the registry's auto-truncate pass, so the full SKILL.md (verified end- to-end with 18.8 KB / 500 lines agent-browser) reaches the model intact. Also emits a skill.load.full_content log event for auditability.

Empirical impact on the 12 existing skills:

  • System prompt index: 4.6 KB total (only tool-builder 614→500 is trimmed)
  • Load on demand: previously 8/12 skills lost their tail; now all 12 are delivered in full

Tests: 15 new in tests/tool/test_skill_tool_description.py covering truncation algorithm, build_description output, and end-to-end no-truncation through ToolRegistry.execute().

…KILL.md on demand

The `skill` tool exposes two surfaces, both of which were silently dropping
critical content:

1. The tool's meta-description (shipped in every system prompt) listed each
   skill's full frontmatter description (up to 1024 chars). Long descriptions
   bloated the prompt and the model often acted on a partial preview without
   loading the full file.

2. When the model called `skill(name=...)`, ToolRegistry's auto-truncate path
   silently cropped the returned SKILL.md at 10 KB / 200 lines (head-only),
   dropping the workflow steps, references, and constraints that authors
   typically place at the end of the file. Users reported "skill.md 后面的
   感觉就完全丢失了".

This change implements progressive disclosure (mirroring hermes-agent's
`skills_list` / `skill_view` split):

- `build_description()` now caps each skill's preview at
  MAX_SKILL_DESCRIPTION_PREVIEW_CHARS (500) using head + tail truncation,
  preserving both the opening (scope/triggers) and the closing (hard
  constraints like "必须先加载本 skill"). Adds an explicit instruction
  telling the model the previews are summaries and it MUST call
  `skill(name=...)` to load the full SKILL.md before acting.

- `skill_tool_impl()` sets `truncated=True` on its `ToolResult` to opt out
  of the registry's auto-truncate pass, so the full SKILL.md (verified end-
  to-end with 18.8 KB / 500 lines `agent-browser`) reaches the model intact.
  Also emits a `skill.load.full_content` log event for auditability.

Empirical impact on the 12 existing skills:
- System prompt index: 4.6 KB total (only `tool-builder` 614→500 is trimmed)
- Load on demand: previously 8/12 skills lost their tail; now all 12 are
  delivered in full

Tests: 15 new in `tests/tool/test_skill_tool_description.py` covering
truncation algorithm, build_description output, and end-to-end no-truncation
through `ToolRegistry.execute()`.

Made-with: Cursor
@duguwanglong duguwanglong requested a review from xiami762 April 24, 2026 08:16
@xiami762 xiami762 merged commit 4b9c57b into main Apr 24, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants