fix(tool/skill): cap description preview at 500 chars and load full S…#185
Merged
fix(tool/skill): cap description preview at 500 chars and load full S…#185
Conversation
…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
xiami762
approved these changes
Apr 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
skilltool exposes two surfaces, both of which were silently dropping critical content: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.
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_viewsplit):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 callskill(name=...)to load the full SKILL.md before acting.skill_tool_impl()setstruncated=Trueon itsToolResultto opt out of the registry's auto-truncate pass, so the full SKILL.md (verified end- to-end with 18.8 KB / 500 linesagent-browser) reaches the model intact. Also emits askill.load.full_contentlog event for auditability.Empirical impact on the 12 existing skills:
tool-builder614→500 is trimmed)Tests: 15 new in
tests/tool/test_skill_tool_description.pycovering truncation algorithm, build_description output, and end-to-end no-truncation throughToolRegistry.execute().