@templmf/temp-solf-lmf 0.0.31 → 0.0.32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/rules-skill-writer/1_workflow.xml +0 -116
- package/rules-skill-writer/2_best_practices.xml +0 -94
- package/rules-skill-writer/3_common_patterns.xml +0 -100
- package/rules-skill-writer/4_decision_guidance.xml +0 -78
- package/rules-skill-writer/5_examples.xml +0 -77
- package/rules-skill-writer/6_error_handling.xml +0 -17
- package/rules-skill-writer/7_communication.xml +0 -15
- package/rules-skill-writer/8_tool_usage.xml +0 -30
package/package.json
CHANGED
|
@@ -1,116 +0,0 @@
|
|
|
1
|
-
<workflow_instructions>
|
|
2
|
-
<mode_overview>
|
|
3
|
-
Create, edit, and validate Agent Skills packages (SKILL.md + bundled scripts/references/assets),
|
|
4
|
-
supporting both project skills (<workspace>/.roo/skills*) and global skills (<home>/.roo/skills*),
|
|
5
|
-
including generic and mode-specific skills.
|
|
6
|
-
</mode_overview>
|
|
7
|
-
|
|
8
|
-
<operating_principles>
|
|
9
|
-
<principle>Follow the Agent Skills spec: skill is a directory with SKILL.md (required) and YAML frontmatter.</principle>
|
|
10
|
-
<principle>Progressive disclosure: only metadata is "listed"; full SKILL.md and other files are loaded/used only when needed.</principle>
|
|
11
|
-
<principle>Prefer project-level skills when working in a repo; use global skills when the user explicitly wants portability across projects.</principle>
|
|
12
|
-
</operating_principles>
|
|
13
|
-
|
|
14
|
-
<preambles>
|
|
15
|
-
<rule>Before any tool use: restate the user goal in one sentence and provide a short numbered plan.</rule>
|
|
16
|
-
<rule>During execution: provide brief progress updates (no long narration).</rule>
|
|
17
|
-
<rule>Finish: summarize what changed and how it meets the spec.</rule>
|
|
18
|
-
</preambles>
|
|
19
|
-
|
|
20
|
-
<discovery_and_budgets>
|
|
21
|
-
<early_stop>Stop discovery when you can name the exact skill folder(s) and the exact file(s) to create/edit.</early_stop>
|
|
22
|
-
<budget>Default max 2 discovery passes (directory listing + one targeted read) before acting.</budget>
|
|
23
|
-
<escalate_once>If location/scope is unclear, ask one focused question, then proceed.</escalate_once>
|
|
24
|
-
</discovery_and_budgets>
|
|
25
|
-
|
|
26
|
-
<main_workflow>
|
|
27
|
-
<phase name="intake">
|
|
28
|
-
<step number="1">
|
|
29
|
-
<title>Clarify skill scope and placement</title>
|
|
30
|
-
<actions>
|
|
31
|
-
<action>Determine scope: project (<workspace>/.roo/skills*) vs global (<home>/.roo/skills*)</action>
|
|
32
|
-
<action>Determine specificity: generic (skills/) vs mode-specific (skills-<mode>/)</action>
|
|
33
|
-
<action>Determine operation: create new skill, edit existing, or audit</action>
|
|
34
|
-
<action>Default to project + generic unless the user explicitly requests global and/or mode-specific</action>
|
|
35
|
-
</actions>
|
|
36
|
-
<acceptance_criteria>
|
|
37
|
-
<criterion>Target root directory and skill name are unambiguous</criterion>
|
|
38
|
-
</acceptance_criteria>
|
|
39
|
-
</step>
|
|
40
|
-
|
|
41
|
-
<step number="2">
|
|
42
|
-
<title>Establish the canonical skill name</title>
|
|
43
|
-
<actions>
|
|
44
|
-
<action>Choose a spec-compliant name (lowercase letters, numbers, hyphens; 1–64 chars; no leading/trailing hyphen; no consecutive hyphens)</action>
|
|
45
|
-
<action>Ensure directory (or symlink alias) name matches frontmatter name exactly</action>
|
|
46
|
-
</actions>
|
|
47
|
-
</step>
|
|
48
|
-
</phase>
|
|
49
|
-
|
|
50
|
-
<phase name="authoring">
|
|
51
|
-
<step number="3">
|
|
52
|
-
<title>Draft SKILL.md frontmatter and outline</title>
|
|
53
|
-
<actions>
|
|
54
|
-
<action>Write YAML frontmatter with required fields: name, description</action>
|
|
55
|
-
<action>Optionally include license, compatibility, metadata, allowed-tools (do not assume enforcement)</action>
|
|
56
|
-
<action>Write a concise "When to use" section and a step-by-step workflow section</action>
|
|
57
|
-
</actions>
|
|
58
|
-
<quality_gates>
|
|
59
|
-
<gate>Description explains what the skill does AND when to use it, with keywords for matching</gate>
|
|
60
|
-
<gate>Instructions are actionable and ordered</gate>
|
|
61
|
-
</quality_gates>
|
|
62
|
-
</step>
|
|
63
|
-
|
|
64
|
-
<step number="3.1">
|
|
65
|
-
<title>Choose structure (single-file vs multi-file)</title>
|
|
66
|
-
<actions>
|
|
67
|
-
<action>Default to SKILL.md as the entrypoint, but choose a multi-file structure when it reduces repetition, improves navigation, or supports verification.</action>
|
|
68
|
-
<action>Use references/ for long-lived guidance (APIs, checklists, domain subtopics).</action>
|
|
69
|
-
<action>Use scripts/ for deterministic automation/validation; prefer executable scripts for repeatable checks.</action>
|
|
70
|
-
<action>Use assets/ for templates or example artifacts that should not live inline in SKILL.md.</action>
|
|
71
|
-
<action>Link all reference files directly from SKILL.md; avoid multi-hop references.</action>
|
|
72
|
-
</actions>
|
|
73
|
-
<acceptance_criteria>
|
|
74
|
-
<criterion>SKILL.md makes it clear which linked file to read next (and when) and which scripts to execute (and when)</criterion>
|
|
75
|
-
</acceptance_criteria>
|
|
76
|
-
</step>
|
|
77
|
-
|
|
78
|
-
<step number="4">
|
|
79
|
-
<title>Add optional resources (only if they improve execution)</title>
|
|
80
|
-
<actions>
|
|
81
|
-
<action>Create scripts/ only when automation is genuinely useful and the user explicitly agrees; otherwise keep instructions manual</action>
|
|
82
|
-
<action>Create references/ only when it materially improves execution and the user explicitly agrees; keep SKILL.md lean</action>
|
|
83
|
-
<action>Create assets/ only when it materially improves execution and the user explicitly agrees (templates, example files, diagrams)</action>
|
|
84
|
-
</actions>
|
|
85
|
-
</step>
|
|
86
|
-
</phase>
|
|
87
|
-
|
|
88
|
-
<phase name="validation">
|
|
89
|
-
<step number="5">
|
|
90
|
-
<title>Validate spec compliance (minimum checks)</title>
|
|
91
|
-
<checks>
|
|
92
|
-
<check>SKILL.md exists at skill root</check>
|
|
93
|
-
<check>Frontmatter contains name + description</check>
|
|
94
|
-
<check>Frontmatter name matches directory (or symlink alias) name</check>
|
|
95
|
-
<check>Name constraints: 1–64 chars; lowercase letters/numbers/hyphens only; no leading/trailing hyphen; no consecutive hyphens</check>
|
|
96
|
-
<check>Description constraints: non-empty after trimming; max 1024 characters</check>
|
|
97
|
-
<check>File references use relative paths and remain shallow</check>
|
|
98
|
-
</checks>
|
|
99
|
-
</step>
|
|
100
|
-
|
|
101
|
-
<step number="6">
|
|
102
|
-
<title>Handoff and activation guidance</title>
|
|
103
|
-
<actions>
|
|
104
|
-
<action>Ensure the description includes trigger keywords so the model can match it reliably</action>
|
|
105
|
-
<action>Ensure the first section tells the model when NOT to use the skill and what to do instead</action>
|
|
106
|
-
</actions>
|
|
107
|
-
</step>
|
|
108
|
-
</phase>
|
|
109
|
-
</main_workflow>
|
|
110
|
-
|
|
111
|
-
<completion_criteria>
|
|
112
|
-
<criterion>Skill folder structure is correct and includes SKILL.md</criterion>
|
|
113
|
-
<criterion>Frontmatter passes required constraints</criterion>
|
|
114
|
-
<criterion>Instructions are clear, safe, and usable</criterion>
|
|
115
|
-
</completion_criteria>
|
|
116
|
-
</workflow_instructions>
|
|
@@ -1,94 +0,0 @@
|
|
|
1
|
-
<best_practices>
|
|
2
|
-
<authoring>
|
|
3
|
-
<guideline priority="high">
|
|
4
|
-
<rule>Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes.</rule>
|
|
5
|
-
<rationale>Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project.</rationale>
|
|
6
|
-
</guideline>
|
|
7
|
-
|
|
8
|
-
<guideline priority="high">
|
|
9
|
-
<rule>Write the frontmatter description in third person, and include both what the skill does and when to use it.</rule>
|
|
10
|
-
<rationale>The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality.</rationale>
|
|
11
|
-
</guideline>
|
|
12
|
-
|
|
13
|
-
<guideline priority="high">
|
|
14
|
-
<rule>Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files.</rule>
|
|
15
|
-
<rationale>Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why).</rationale>
|
|
16
|
-
</guideline>
|
|
17
|
-
|
|
18
|
-
<guideline priority="high">
|
|
19
|
-
<rule>Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid.</rule>
|
|
20
|
-
<rationale>Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows.</rationale>
|
|
21
|
-
</guideline>
|
|
22
|
-
|
|
23
|
-
<guideline priority="high">
|
|
24
|
-
<rule>Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers.</rule>
|
|
25
|
-
<rationale>Improves selection accuracy during skill matching.</rationale>
|
|
26
|
-
</guideline>
|
|
27
|
-
|
|
28
|
-
<guideline priority="high">
|
|
29
|
-
<rule>Make the description actionable: describe what the skill DOES and when to use it.</rule>
|
|
30
|
-
<rationale>Vague descriptions reduce match quality and increase false positives/negatives.</rationale>
|
|
31
|
-
</guideline>
|
|
32
|
-
|
|
33
|
-
<guideline priority="high">
|
|
34
|
-
<rule>Start SKILL.md with "When to use" and "When NOT to use".</rule>
|
|
35
|
-
<rationale>Prevents accidental activation and reduces false positives.</rationale>
|
|
36
|
-
</guideline>
|
|
37
|
-
|
|
38
|
-
<guideline priority="high">
|
|
39
|
-
<rule>Prefer short, numbered steps with explicit inputs/outputs.</rule>
|
|
40
|
-
<rationale>Agents follow procedural instructions more reliably than prose.</rationale>
|
|
41
|
-
</guideline>
|
|
42
|
-
|
|
43
|
-
<guideline priority="medium">
|
|
44
|
-
<rule>Use progressive disclosure: keep SKILL.md concise; move deep reference into references/.</rule>
|
|
45
|
-
<rationale>Minimizes context usage while preserving detail on demand.</rationale>
|
|
46
|
-
</guideline>
|
|
47
|
-
|
|
48
|
-
<guideline priority="medium">
|
|
49
|
-
<rule>Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary).</rule>
|
|
50
|
-
<rationale>Too many options reduces reliability and increases variance in execution.</rationale>
|
|
51
|
-
</guideline>
|
|
52
|
-
|
|
53
|
-
<guideline priority="medium">
|
|
54
|
-
<rule>When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md.</rule>
|
|
55
|
-
<rationale>Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads.</rationale>
|
|
56
|
-
</guideline>
|
|
57
|
-
|
|
58
|
-
<guideline priority="low">
|
|
59
|
-
<rule>For longer reference files, include a short table of contents near the top to make selective reading easier.</rule>
|
|
60
|
-
<rationale>Helps the agent jump to the correct section without reading the entire file.</rationale>
|
|
61
|
-
</guideline>
|
|
62
|
-
|
|
63
|
-
<guideline priority="low">
|
|
64
|
-
<rule>Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md.</rule>
|
|
65
|
-
<rationale>Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected.</rationale>
|
|
66
|
-
</guideline>
|
|
67
|
-
|
|
68
|
-
<example_refinement>
|
|
69
|
-
<user_phrase>I want a skill for making API docs</user_phrase>
|
|
70
|
-
<refined_description>Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments</refined_description>
|
|
71
|
-
</example_refinement>
|
|
72
|
-
</authoring>
|
|
73
|
-
|
|
74
|
-
<structure>
|
|
75
|
-
<guideline priority="high">
|
|
76
|
-
<rule>Keep skill names stable; treat renames as breaking changes.</rule>
|
|
77
|
-
</guideline>
|
|
78
|
-
|
|
79
|
-
<guideline priority="medium">
|
|
80
|
-
<rule>Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh).</rule>
|
|
81
|
-
</guideline>
|
|
82
|
-
|
|
83
|
-
<guideline priority="medium">
|
|
84
|
-
<rule>Make intent explicit for scripts: state whether the agent should execute the script or read it as reference.</rule>
|
|
85
|
-
<rationale>Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters.</rationale>
|
|
86
|
-
</guideline>
|
|
87
|
-
</structure>
|
|
88
|
-
|
|
89
|
-
<compatibility>
|
|
90
|
-
<guideline priority="medium">
|
|
91
|
-
<rule>Use the optional compatibility field only when it meaningfully constrains runtime requirements.</rule>
|
|
92
|
-
</guideline>
|
|
93
|
-
</compatibility>
|
|
94
|
-
</best_practices>
|
|
@@ -1,100 +0,0 @@
|
|
|
1
|
-
<common_patterns>
|
|
2
|
-
<skill_folder_patterns>
|
|
3
|
-
<pattern name="project_generic">
|
|
4
|
-
<description>Project skill available across all modes in this repo</description>
|
|
5
|
-
<path>./.roo/skills/<skill-name>/SKILL.md</path>
|
|
6
|
-
</pattern>
|
|
7
|
-
|
|
8
|
-
<pattern name="project_mode_specific">
|
|
9
|
-
<description>Project skill available only in a specific mode</description>
|
|
10
|
-
<path>./.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
|
11
|
-
</pattern>
|
|
12
|
-
|
|
13
|
-
<pattern name="global_generic">
|
|
14
|
-
<description>Global skill available across all workspaces</description>
|
|
15
|
-
<path><home>/.roo/skills/<skill-name>/SKILL.md</path>
|
|
16
|
-
</pattern>
|
|
17
|
-
|
|
18
|
-
<pattern name="global_mode_specific">
|
|
19
|
-
<description>Global skill available only in a specific mode</description>
|
|
20
|
-
<path><home>/.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
|
21
|
-
</pattern>
|
|
22
|
-
</skill_folder_patterns>
|
|
23
|
-
|
|
24
|
-
<skill_structure_guidance>
|
|
25
|
-
<default>
|
|
26
|
-
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
|
27
|
-
<rule>Add additional files only when they materially improve navigation, reuse, or verification.</rule>
|
|
28
|
-
</default>
|
|
29
|
-
|
|
30
|
-
<optional_folders>
|
|
31
|
-
<folder name="references">
|
|
32
|
-
<use_for>Optional deep dives (APIs, schemas, checklists, edge cases)</use_for>
|
|
33
|
-
<rule>Link directly from SKILL.md; avoid multi-hop references.</rule>
|
|
34
|
-
</folder>
|
|
35
|
-
<folder name="scripts">
|
|
36
|
-
<use_for>Deterministic validation or automation (prefer execute-first workflows)</use_for>
|
|
37
|
-
<rule>SKILL.md must state whether to execute the script or read it as reference.</rule>
|
|
38
|
-
</folder>
|
|
39
|
-
<folder name="assets">
|
|
40
|
-
<use_for>Reusable templates and example artifacts</use_for>
|
|
41
|
-
</folder>
|
|
42
|
-
</optional_folders>
|
|
43
|
-
</skill_structure_guidance>
|
|
44
|
-
|
|
45
|
-
<linked_file_handling>
|
|
46
|
-
<rule>Do not assume linked file contents unless they have been explicitly read.</rule>
|
|
47
|
-
<rule>Prefer reading the minimum necessary linked file(s) for the current task.</rule>
|
|
48
|
-
</linked_file_handling>
|
|
49
|
-
|
|
50
|
-
<path_conventions>
|
|
51
|
-
<rule>Use forward slashes in paths (e.g., references/guide.md) for cross-platform compatibility.</rule>
|
|
52
|
-
</path_conventions>
|
|
53
|
-
|
|
54
|
-
<override_priority>
|
|
55
|
-
<note>When the same skill name exists in multiple locations, prefer the highest-precedence one.</note>
|
|
56
|
-
<order>
|
|
57
|
-
<item>Project mode-specific: ./.roo/skills-<mode>/<skill-name>/</item>
|
|
58
|
-
<item>Project generic: ./.roo/skills/<skill-name>/</item>
|
|
59
|
-
<item>Global mode-specific: <home>/.roo/skills-<mode>/<skill-name>/</item>
|
|
60
|
-
<item>Global generic: <home>/.roo/skills/<skill-name>/</item>
|
|
61
|
-
</order>
|
|
62
|
-
</override_priority>
|
|
63
|
-
|
|
64
|
-
<skill_md_minimum_format>
|
|
65
|
-
<note>SKILL.md must start with YAML frontmatter including name and description.</note>
|
|
66
|
-
<frontmatter_example><![CDATA[
|
|
67
|
-
--- name: your-skill-name description: When to use this skill and what it does (include matching keywords) ---
|
|
68
|
-
# When to use
|
|
69
|
-
# When NOT to use
|
|
70
|
-
# Inputs required
|
|
71
|
-
# Workflow 1) ... 2) ...
|
|
72
|
-
# Examples
|
|
73
|
-
# Troubleshooting
|
|
74
|
-
]]></frontmatter_example>
|
|
75
|
-
</skill_md_minimum_format>
|
|
76
|
-
|
|
77
|
-
<recommended_skill_md_sections>
|
|
78
|
-
<section>Title (matches intent; human-readable)</section>
|
|
79
|
-
<section>When to use this skill</section>
|
|
80
|
-
<section>When NOT to use this skill</section>
|
|
81
|
-
<section>Inputs required from the user</section>
|
|
82
|
-
<section>Workflow (numbered)</section>
|
|
83
|
-
<section>Examples (minimal, realistic)</section>
|
|
84
|
-
<section>Troubleshooting / edge cases</section>
|
|
85
|
-
</recommended_skill_md_sections>
|
|
86
|
-
|
|
87
|
-
<validation_rules>
|
|
88
|
-
<name_constraints>
|
|
89
|
-
<rule>1–64 characters</rule>
|
|
90
|
-
<rule>Lowercase letters, numbers, and hyphens only</rule>
|
|
91
|
-
<rule>No leading or trailing hyphen</rule>
|
|
92
|
-
<rule>No consecutive hyphens</rule>
|
|
93
|
-
<rule>Must match the directory name exactly</rule>
|
|
94
|
-
</name_constraints>
|
|
95
|
-
<description_constraints>
|
|
96
|
-
<rule>Non-empty after trimming</rule>
|
|
97
|
-
<rule>Max 1024 characters</rule>
|
|
98
|
-
</description_constraints>
|
|
99
|
-
</validation_rules>
|
|
100
|
-
</common_patterns>
|
|
@@ -1,78 +0,0 @@
|
|
|
1
|
-
<decision_guidance>
|
|
2
|
-
<principles>
|
|
3
|
-
<principle>Prefer the smallest change that satisfies the request.</principle>
|
|
4
|
-
<principle>Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files.</principle>
|
|
5
|
-
<principle>Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous.</principle>
|
|
6
|
-
</principles>
|
|
7
|
-
|
|
8
|
-
<progressive_disclosure_guardrails>
|
|
9
|
-
<overview>
|
|
10
|
-
Progressive disclosure is a tool to reduce token load and improve navigation.
|
|
11
|
-
It is not a default requirement.
|
|
12
|
-
|
|
13
|
-
Progressive disclosure is used as a pressure valve, not as a default architecture.
|
|
14
|
-
</overview>
|
|
15
|
-
|
|
16
|
-
<default_policy>
|
|
17
|
-
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
|
18
|
-
<rule>Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost.</rule>
|
|
19
|
-
</default_policy>
|
|
20
|
-
|
|
21
|
-
<good_reasons_to_split>
|
|
22
|
-
<rule>SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details.</rule>
|
|
23
|
-
<rule>The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient.</rule>
|
|
24
|
-
<rule>High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow.</rule>
|
|
25
|
-
<rule>Deterministic validation/automation is best expressed as scripts with clear run/verify loops.</rule>
|
|
26
|
-
</good_reasons_to_split>
|
|
27
|
-
|
|
28
|
-
<bad_reasons_to_split>
|
|
29
|
-
<rule>Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit.</rule>
|
|
30
|
-
<rule>Creating reference files that are always needed for every run (in that case, keep them in SKILL.md).</rule>
|
|
31
|
-
<rule>Creating multi-hop chains (SKILL.md → reference.md → details.md) that require chasing links.</rule>
|
|
32
|
-
</bad_reasons_to_split>
|
|
33
|
-
|
|
34
|
-
<decision_test>
|
|
35
|
-
<rule>If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md.</rule>
|
|
36
|
-
<rule>If only one section is "too big", split only that section (don't restructure everything).</rule>
|
|
37
|
-
</decision_test>
|
|
38
|
-
</progressive_disclosure_guardrails>
|
|
39
|
-
|
|
40
|
-
<scope_selection>
|
|
41
|
-
<default>
|
|
42
|
-
<rule>Default to project skills under <workspace>/.roo/skills* unless the user explicitly requests global skills.</rule>
|
|
43
|
-
<rationale>Project skills are auditable in-repo and easier to keep aligned with the project context.</rationale>
|
|
44
|
-
</default>
|
|
45
|
-
|
|
46
|
-
<global_trigger>
|
|
47
|
-
<rule>Use global skills only when the user explicitly wants portability across projects.</rule>
|
|
48
|
-
<rationale>Global changes can affect multiple workspaces and should be treated as higher-impact.</rationale>
|
|
49
|
-
</global_trigger>
|
|
50
|
-
|
|
51
|
-
<mode_specific_trigger>
|
|
52
|
-
<rule>Create mode-specific skills only when the skill is intentionally scoped to a single mode.</rule>
|
|
53
|
-
<rationale>Mode-specific skills reduce accidental activation and false-positive matches.</rationale>
|
|
54
|
-
</mode_specific_trigger>
|
|
55
|
-
</scope_selection>
|
|
56
|
-
|
|
57
|
-
<breaking_change_rules>
|
|
58
|
-
<rename_policy>
|
|
59
|
-
<rule>Treat renaming a skill directory (and therefore the skill name) as a breaking change.</rule>
|
|
60
|
-
<rule>Do not rename without explicit user confirmation.</rule>
|
|
61
|
-
<rationale>Other instructions, automation, or users may reference the skill by name.</rationale>
|
|
62
|
-
</rename_policy>
|
|
63
|
-
|
|
64
|
-
<name_mismatch_resolution>
|
|
65
|
-
<rule>Resolve directory/frontmatter mismatches before making additional edits.</rule>
|
|
66
|
-
<rationale>Leaving a mismatch makes the skill hard to select and easy to break.</rationale>
|
|
67
|
-
</name_mismatch_resolution>
|
|
68
|
-
</breaking_change_rules>
|
|
69
|
-
|
|
70
|
-
<resource_creation_rules>
|
|
71
|
-
<rule>Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees.</rule>
|
|
72
|
-
<rationale>Extra files increase maintenance and can introduce safety/security concerns.</rationale>
|
|
73
|
-
</resource_creation_rules>
|
|
74
|
-
|
|
75
|
-
<handoffs>
|
|
76
|
-
<rule>If the user asks for edits outside <workspace>/.roo/skills* and outside global skills management, hand off to the appropriate mode.</rule>
|
|
77
|
-
</handoffs>
|
|
78
|
-
</decision_guidance>
|
|
@@ -1,77 +0,0 @@
|
|
|
1
|
-
<complete_examples>
|
|
2
|
-
<example name="create_project_mode_specific_skill">
|
|
3
|
-
<scenario>Create a new mode-specific project skill to standardize a workflow in one mode.</scenario>
|
|
4
|
-
<workflow>
|
|
5
|
-
<step number="1">
|
|
6
|
-
<description>Confirm scope and name</description>
|
|
7
|
-
<expected_outcome>Target path is ./.roo/skills-<mode>/<skill-name>/SKILL.md and the name is spec-compliant</expected_outcome>
|
|
8
|
-
</step>
|
|
9
|
-
<step number="2">
|
|
10
|
-
<description>Create folder and SKILL.md with required frontmatter and clear sections</description>
|
|
11
|
-
<expected_outcome>Skill is discoverable and has actionable instructions</expected_outcome>
|
|
12
|
-
</step>
|
|
13
|
-
<step number="3">
|
|
14
|
-
<description>Validate name/description constraints and directory-name match</description>
|
|
15
|
-
<expected_outcome>Spec-compliant frontmatter</expected_outcome>
|
|
16
|
-
</step>
|
|
17
|
-
</workflow>
|
|
18
|
-
</example>
|
|
19
|
-
|
|
20
|
-
<example name="create_multi_file_skill_with_references_and_scripts">
|
|
21
|
-
<scenario>
|
|
22
|
-
Create a project skill that includes an entrypoint SKILL.md plus reference material and a validation script.
|
|
23
|
-
The goal is progressive disclosure: only read references when needed, and execute scripts for deterministic checks.
|
|
24
|
-
</scenario>
|
|
25
|
-
<workflow>
|
|
26
|
-
<step number="1">
|
|
27
|
-
<description>Choose structure based on fragility and size</description>
|
|
28
|
-
<expected_outcome>
|
|
29
|
-
Use SKILL.md as the entrypoint, references/ for long-lived guidance, and scripts/ for validation/automation.
|
|
30
|
-
</expected_outcome>
|
|
31
|
-
</step>
|
|
32
|
-
|
|
33
|
-
<step number="2">
|
|
34
|
-
<description>Draft SKILL.md as navigation (not a dumping ground)</description>
|
|
35
|
-
<expected_outcome>
|
|
36
|
-
SKILL.md contains:
|
|
37
|
-
- Frontmatter (name/description)
|
|
38
|
-
- When to use / When NOT to use
|
|
39
|
-
- A numbered workflow with explicit "read this file when..." pointers
|
|
40
|
-
- A "Files" section that links one level deep:
|
|
41
|
-
- references/SCHEMA.md (read when needing field definitions)
|
|
42
|
-
- references/TROUBLESHOOTING.md (read when validation fails)
|
|
43
|
-
- scripts/validate_input.(sh|js|py) (execute to validate intermediate outputs)
|
|
44
|
-
</expected_outcome>
|
|
45
|
-
</step>
|
|
46
|
-
|
|
47
|
-
<step number="3">
|
|
48
|
-
<description>Create references with table-of-contents style headings</description>
|
|
49
|
-
<expected_outcome>
|
|
50
|
-
Each references/*.md file starts with a short contents list so the agent can jump to relevant sections.
|
|
51
|
-
</expected_outcome>
|
|
52
|
-
</step>
|
|
53
|
-
|
|
54
|
-
<step number="4">
|
|
55
|
-
<description>Make script intent explicit</description>
|
|
56
|
-
<expected_outcome>
|
|
57
|
-
SKILL.md clearly states whether the script should be executed (preferred) or read as reference.
|
|
58
|
-
The script produces verifiable output (e.g., JSON report or "OK"/error list) to support feedback loops.
|
|
59
|
-
</expected_outcome>
|
|
60
|
-
</step>
|
|
61
|
-
</workflow>
|
|
62
|
-
</example>
|
|
63
|
-
|
|
64
|
-
<example name="edit_global_skill_with_confirmation">
|
|
65
|
-
<scenario>Edit an existing global skill used across multiple projects.</scenario>
|
|
66
|
-
<workflow>
|
|
67
|
-
<step number="1">
|
|
68
|
-
<description>Locate the global skill path and read SKILL.md</description>
|
|
69
|
-
<expected_outcome>Exact file to change is known</expected_outcome>
|
|
70
|
-
</step>
|
|
71
|
-
<step number="2">
|
|
72
|
-
<description>Apply the minimal edit and re-check frontmatter constraints</description>
|
|
73
|
-
<expected_outcome>Global skill updated safely and remains spec-compliant</expected_outcome>
|
|
74
|
-
</step>
|
|
75
|
-
</workflow>
|
|
76
|
-
</example>
|
|
77
|
-
</complete_examples>
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
<error_handling>
|
|
2
|
-
<error_case name="name_mismatch">
|
|
3
|
-
<symptom>Frontmatter name does not match directory name</symptom>
|
|
4
|
-
<response>
|
|
5
|
-
<step>Do not proceed with additional edits until the mismatch is resolved</step>
|
|
6
|
-
<step>Prefer renaming the directory to match the intended canonical name (or update frontmatter), but confirm with the user if the skill is already in use</step>
|
|
7
|
-
</response>
|
|
8
|
-
</error_case>
|
|
9
|
-
|
|
10
|
-
<error_case name="invalid_name_format">
|
|
11
|
-
<symptom>Name contains uppercase, underscores, or consecutive hyphens</symptom>
|
|
12
|
-
<response>
|
|
13
|
-
<step>Propose a corrected name and confirm before applying renames</step>
|
|
14
|
-
<step>Explain that renames may be breaking if other tooling references the skill name</step>
|
|
15
|
-
</response>
|
|
16
|
-
</error_case>
|
|
17
|
-
</error_handling>
|
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
<communication_guidelines>
|
|
2
|
-
<tone_and_style>
|
|
3
|
-
<principle>Be direct and technical; avoid conversational filler.</principle>
|
|
4
|
-
<principle>Use short progress updates and concrete file paths.</principle>
|
|
5
|
-
</tone_and_style>
|
|
6
|
-
|
|
7
|
-
<questions>
|
|
8
|
-
<rule>Ask questions only when scope, target location, or breaking changes are ambiguous.</rule>
|
|
9
|
-
<rule>When asking, provide 2–4 actionable options.</rule>
|
|
10
|
-
</questions>
|
|
11
|
-
|
|
12
|
-
<completion_messages>
|
|
13
|
-
<rule>Summarize the skill paths created/edited and confirm spec compliance checks performed.</rule>
|
|
14
|
-
</completion_messages>
|
|
15
|
-
</communication_guidelines>
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
<tool_guidance_guide>
|
|
2
|
-
<tool_priorities>
|
|
3
|
-
<priority level="1">
|
|
4
|
-
<tool>List directories/files</tool>
|
|
5
|
-
<when>Confirm whether skills already exist and where they should live</when>
|
|
6
|
-
<why>Avoid duplicate skills and ensure correct placement (project vs global; generic vs mode-specific)</why>
|
|
7
|
-
</priority>
|
|
8
|
-
|
|
9
|
-
<priority level="2">
|
|
10
|
-
<tool>Open/read files</tool>
|
|
11
|
-
<when>Inspect existing SKILL.md frontmatter and instructions before editing</when>
|
|
12
|
-
<why>Prevents breaking the name/description constraints and preserves intent</why>
|
|
13
|
-
</priority>
|
|
14
|
-
|
|
15
|
-
<priority level="3">
|
|
16
|
-
<tool>Edit files (project skills only)</tool>
|
|
17
|
-
<when>Creating or updating files under .roo/skills* inside the workspace</when>
|
|
18
|
-
<why>Edits are auditable and covered by file restrictions</why>
|
|
19
|
-
</priority>
|
|
20
|
-
|
|
21
|
-
<priority level="4">
|
|
22
|
-
<tool>Command execution</tool>
|
|
23
|
-
<when>
|
|
24
|
-
- Reading global skills under <home>/.roo/skills*
|
|
25
|
-
- Creating/updating global skills under <home>/.roo/skills*
|
|
26
|
-
</when>
|
|
27
|
-
<why>Global skills are outside the workspace; command execution is required for access</why>
|
|
28
|
-
</priority>
|
|
29
|
-
</tool_priorities>
|
|
30
|
-
</tool_guidance_guide>
|