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