skills polishing and fixing
frdel committed
Feb 2, 2026 at 21:53 UTC
1b4946705f369435c20dd5b91d396a6c77f82edc
6 files changed
+85
-178
prompts/agent.system.tool.skills.md
+32
-164
@@ -1,63 +1,39 @@
1
### skills_tool
2
3
-manage and use agent skills for specialized capabilities
4
-skills are composable bundles of instructions context and executable code
5
-use progressive disclosure: metadata → full content → referenced files
6
-use "method" arg to specify operation: "list" "load" "read_file" "search"
3
+#### overview
4
8
-## Overview
5
+skills are folders with instructions scripts files
6
+give agent extra capabilities
7
+agentskills.io standard
8
10
-Skills system provides three-level progressive disclosure:
11
-- Level 1: Metadata (name + description) loaded in system prompt at startup
12
-- Level 2: Full SKILL.md content loaded when relevant to task
13
-- Level 3+: Referenced files loaded on-demand
9
+#### workflow
10
+1. skill list titles descriptions in system prompt section available skills
11
+2. use skills_tool:load to get full skill instructions and context
12
+4. use code_execution_tool to run scripts or read files
13
15
-When to use skills:
16
-- Task matches skill description from available skills list
17
-- Need specialized procedures or domain knowledge
18
-- Task requires bundled scripts or automation
19
-- Need step-by-step guidance for complex operations
14
+#### examples
15
21
-Progressive workflow:
22
-1. Check available skills metadata already in your context
23
-2. Use "search" if looking for specific capability
24
-3. Use "load" to get full skill instructions and context
25
-4. Use "read_file" to load additional reference documents
26
-5. Use code_execution_tool to run any scripts referenced by the skill
16
+##### skills_tool:list
17
28
-## Operations
29
-
30
-### 1. list available skills
31
-
32
-Lists all available skills with metadata
33
-Shows name, version, description, tags, and author
34
-Use when: exploring available capabilities or confirming skill exists
18
+list all skills with metadata name version description tags author
19
+only use when details needed
20
21
~~~json
22
{
23
"thoughts": [
39
- "Need to see what skills are available",
40
- "User asked about available capabilities"
24
+ "Need find skills of certain properties...",
25
],
26
"headline": "Listing all available skills",
43
- "tool_name": "skills_tool",
44
- "tool_args": {
45
- "method": "list"
46
- }
27
+ "tool_name": "skills_tool:list",
28
}
29
~~~
30
50
-Response format:
51
-- Skill name and version
52
-- Brief description
53
-- Tags for categorization
54
-- Author attribution
55
-
56
-### 2. load full skill content
31
+##### skills_tool:load
32
58
-Loads complete SKILL.md content with instructions and procedures
59
-Returns metadata, full content, and list of referenced files
60
-Use when: identified relevant skill and need detailed instructions
33
+loads complete SKILL.md content instructions procedures
34
+returns metadata content file tree
35
+use when potential skill identified and want usage instructions
36
+use again when no longer in history
37
38
~~~json
39
{
@@ -67,65 +43,19 @@ Use when: identified relevant skill and need detailed instructions
43
"Loading full skill content"
44
],
45
"headline": "Loading PDF editing skill",
70
- "tool_name": "skills_tool",
46
+ "tool_name": "skills_tool:load",
47
"tool_args": {
72
- "method": "load",
48
"skill_name": "pdf_editing"
49
}
50
}
51
~~~
52
78
-Required args:
79
-- skill_name: exact name from metadata or list
80
-
81
-Response includes:
82
-- Skill metadata (name, version, description, tags)
83
-- Full markdown content with instructions
84
-- List of referenced files available to load
85
-- Code examples and procedures
86
-
87
-### 3. read skill reference file
88
-
89
-Reads additional reference files from skill directory
90
-Files referenced in SKILL.md can be loaded progressively
91
-Use when: need detailed documentation or examples from skill references
92
-
93
-~~~json
94
-{
95
- "thoughts": [
96
- "Skill mentioned forms.md for form filling details",
97
- "Need specific form field handling instructions",
98
- "Loading reference file"
99
- ],
100
- "headline": "Reading PDF forms reference documentation",
101
- "tool_name": "skills_tool",
102
- "tool_args": {
103
- "method": "read_file",
104
- "skill_name": "pdf_editing",
105
- "file_path": "forms.md"
106
- }
107
-}
108
-~~~
109
-
110
-Required args:
111
-- skill_name: name of skill containing file
112
-- file_path: relative path within skill directory (e.g. "reference.md" or "examples/example1.md")
113
-
114
-Security:
115
-- Path validation prevents directory traversal
116
-- Only files within skill directory accessible
117
-- Supports markdown, text, code files
53
+##### executing skill scripts
54
119
-
120
-## Running skill scripts
121
-
122
-When a skill includes scripts (listed under its files), use code_execution_tool with runtime terminal directly to run them.
123
-The skill's "load" output shows the skill directory path and lists available scripts.
124
-Use read_file to inspect a script before running it if needed.
125
-
126
-Example: running a Python script from a skill
127
-1. Load the skill to get its path and script list
128
-2. Use code_execution_tool with runtime="python" to run the script
55
+use skills_tool:load identify skill script files and instructions
56
+use code_execution_tool runtime terminal to execute
57
+write command and parameters as instructed
58
+use full paths or cd to skill directory
59
60
~~~json
61
{
@@ -143,72 +73,10 @@ Example: running a Python script from a skill
73
}
74
~~~
75
146
-## Best Practices
147
-
148
-### When to use skills vs other tools
149
-
150
-Use skills when:
151
-- Task requires specialized domain knowledge
152
-- Need structured procedures or step-by-step guidance
153
-- Complex multi-step operations with best practices
154
-
155
-Use code_execution_tool directly when:
156
-- Running skill scripts (load skill first to get paths)
157
-- Simple file operations
158
-- General computation
159
-
160
-Use other tools when:
161
-- Web search (use search_engine)
162
-- Memory operations (use memory tools)
163
-
164
-### Progressive disclosure workflow
165
-
166
-1. Start with metadata (already in context)
167
- - Check available skills list in system prompt
168
- - Match task to skill description
169
-
170
-2. Load full content when relevant
171
- - Use "load" to get complete instructions
172
- - Review procedures and examples
173
-
174
-3. Load references as needed
175
- - Use "read_file" for detailed documentation
176
- - Load only files relevant to current subtask
177
-
178
-4. Execute scripts via code_execution_tool
179
- - Use skill path from "load" output
180
- - Run scripts directly with code_execution_tool
181
-
182
-### Common patterns
183
-
184
-Pattern: Using a skill for first time
185
-1. Identify skill from metadata
186
-2. Load full skill content
187
-3. Follow instructions in content
188
-4. Load reference files if mentioned
189
-5. Run scripts via code_execution_tool using paths from load output
190
-
191
-Pattern: Exploring capabilities
192
-1. Search with query terms
193
-2. Review matches
194
-3. Load most relevant skill
195
-
196
-## Error Handling
197
-
198
-Common errors:
199
-- "Skill not found": Check spelling, use list or search to find correct name
200
-- "File not found": Verify file_path matches referenced files from load output
201
-
202
-When skill loading fails:
203
-- Verify skill exists using list method
204
-- Check for typos in skill_name
205
-- Ensure skill system is enabled in settings
206
-## Notes
207
-
208
-- Skills metadata already loaded in your system prompt
209
-- Skills cache after first load for efficiency
210
-- Referenced files listed in load response
211
-- Use code_execution_tool to run any scripts provided by skills
212
-- All operations return formatted text responses
213
-- Skills follow the open SKILL.md standard (cross-platform compatible)
214
-- Use skills for structured procedures and contextual expertise
76
+#### skills guide
77
+use skills when relevant for task
78
+load skill before use
79
+read / execute files with code_execution_tool
80
+follow instructions in skill
81
+mind relative paths
82
+conversation history discards old messages use skills_tool:load again when lost
\ No newline at end of file
python/helpers/history.py
+1
-1
@@ -15,7 +15,7 @@ CURRENT_TOPIC_RATIO = 0.5
15
HISTORY_TOPIC_RATIO = 0.3
16
HISTORY_BULK_RATIO = 0.2
17
TOPIC_COMPRESS_RATIO = 0.65
18
-LARGE_MESSAGE_TO_TOPIC_RATIO = 0.25
18
+LARGE_MESSAGE_TO_TOPIC_RATIO = 0.5
19
RAW_MESSAGE_OUTPUT_TEXT_TRIM = 100
20
21
python/helpers/skills.py
+2
-2
@@ -384,8 +384,8 @@ def validate_skill(skill: Skill) -> List[str]:
384
issues.append("name must not start or end with a hyphen")
385
if "--" in name:
386
issues.append("name must not contain consecutive hyphens")
387
- if skill.path and _normalize_name(skill.path.name) != _normalize_name(name):
388
- issues.append("name should match the parent directory name")
387
+ # if skill.path and _normalize_name(skill.path.name) != _normalize_name(name):
388
+ # issues.append("name should match the parent directory name")
389
390
if not desc:
391
issues.append("Missing required field: description")
python/helpers/tool.py
+1
-1
@@ -57,7 +57,7 @@ class Tool:
57
heading = f"icon://construction {self.agent.agent_name}: Using tool '{self.name}:{self.method}'"
58
else:
59
heading = f"icon://construction {self.agent.agent_name}: Using tool '{self.name}'"
60
- return self.agent.context.log.log(type="tool", heading=heading, content="", kvps=self.args)
60
+ return self.agent.context.log.log(type="tool", heading=heading, content="", kvps=self.args, _tool_name=self.name)
61
62
def nice_key(self, key:str):
63
words = key.split('_')
python/tools/skills_tool.py
+13
-7
@@ -5,7 +5,7 @@ from typing import List
5
6
from python.helpers.tool import Tool, Response
7
from python.helpers import projects, files, file_tree
8
-from python.helpers import skills as skills_helper
8
+from python.helpers import skills as skills_helper, runtime
9
10
11
class SkillsTool(Tool):
@@ -134,8 +134,8 @@ class SkillsTool(Tool):
134
135
lines: List[str] = []
136
lines.append(f"Skill: {skill.name}")
137
- lines.append(f"Path: {rel_skill_dir}")
138
- lines.append(f"Runtime path: {runtime_path}")
137
+ # lines.append(f"Path: {rel_skill_dir}")
138
+ lines.append(f"Path: {runtime_path}")
139
if skill.version:
140
lines.append(f"Version: {skill.version}")
141
if skill.author:
@@ -203,9 +203,9 @@ class SkillsTool(Tool):
203
204
def _list_skill_files(self, skill_dir: Path, *, max_files: int = 80) -> str:
205
if not skill_dir.exists():
206
- return []
206
+ return ""
207
208
- tree = file_tree.file_tree(
208
+ tree = str(file_tree.file_tree(
209
str(skill_dir),
210
max_depth=10,
211
folders_first=True,
@@ -214,5 +214,11 @@ class SkillsTool(Tool):
214
output_mode="string",
215
max_lines=300,
216
ignore=files.read_file("conf/skill.default.gitignore"),
217
- )
218
- return tree
217
+ ))
218
+
219
+ # replace absolute path with runtime path (for dev env only)
220
+ if tree and runtime.is_development():
221
+ runtime_path = files.normalize_a0_path(str(skill_dir))
222
+ tree = tree.replace(str(skill_dir), runtime_path)
223
+
224
+ return str(tree)
webui/js/messages.js
+36
-3
@@ -940,10 +940,43 @@ export function drawMessageTool({
940
agentno = 0,
941
...additional
942
}) {
943
+
944
+ const tool_name = kvps?._tool_name || "";
945
+
946
+ if(!tool_name){
947
+ return drawMessageToolSimple({ ...arguments[0] });
948
+ } else if (kvps._tool_name === "skills_tool") {
949
+ return drawMessageToolSimple({ ...arguments[0], code: "SKL" });
950
+ } else if (kvps._tool_name === "vision_load") {
951
+ return drawMessageToolSimple({ ...arguments[0], code: "EYE" });
952
+ } else if (kvps._tool_name === "search_engine") {
953
+ return drawMessageToolSimple({ ...arguments[0], code: "WEB" });
954
+ } else if (kvps._tool_name === "browser_agent") {
955
+ return drawMessageToolSimple({ ...arguments[0], code: "WWW" });
956
+ } else if (kvps._tool_name.startsWith("memory_")) {
957
+ return drawMessageToolSimple({ ...arguments[0], code: "MEM" });
958
+ } else {
959
+ return drawMessageToolSimple({ ...arguments[0] });
960
+ }
961
+
962
+}
963
+
964
+export function drawMessageToolSimple({
965
+ id,
966
+ type,
967
+ heading,
968
+ content,
969
+ kvps = null,
970
+ timestamp = null,
971
+ agentno = 0,
972
+ code,
973
+ displayKvps,
974
+ ...additional
975
+}) {
976
const title = cleanStepTitle(heading);
944
- let displayKvps = { ...kvps };
977
+ displayKvps = displayKvps || { ...kvps };
978
const headerLabels = [
946
- kvps?.tool_name && { label: kvps.tool_name, class: "tool-name-badge" },
979
+ kvps?._tool_name && { label: kvps._tool_name, class: "tool-name-badge" },
980
].filter(Boolean);
981
const contentText = String(content ?? "");
982
const actionButtons = contentText.trim()
@@ -961,7 +994,7 @@ export function drawMessageTool({
994
return drawProcessStep({
995
id,
996
title,
964
- code: "USE",
997
+ code: code || "USE",
998
classes: null,
999
kvps: displayKvps,
1000
content,