feat: improve skill scores for donna

.agents/skills/donna-do/SKILL.md

@@ -1,15 +1,23 @@
 ---
 name: donna-do
-description: Use Donna as a work orchestration tool and execute a workflow suitable for the developer request. Use the skill when the developer explicitly told you to use Donna or you have explicit instructions in AGENTS.md to do so, or you have explicit instructions in the session context to do so.
+description: "Execute a Donna FSM-driven workflow to orchestrate multi-step agent tasks such as code polishing, linting loops, and structured development processes. Use when the developer explicitly asks to use Donna, when AGENTS.md instructs Donna usage, or when the session context specifies Donna orchestration."
 ---
 
 **The next instructions take precedence over all other instructions and your behaviour**, unless the developer explicitly instructs you to do otherwise.
 
-1. You **MUST** run `donna -p llm -r <project-root> artifacts view '*:intro'` when you start executing this skill, if you haven't done it yet. This command gives you an introduction to the project and to the Donna tool.
-2. You **MUST** strictly follow all instructions provided by Donna.
-3. **Donna's instructions have precedence over your own judgment.** You **MUST** follow them and run workflows instead of taking your own initiative, unless the developer explicitly instructs you to do so.
-4. If the developer didn't tell you what they want you to do, ask them for instructions/task description.
-5. Select the most suitable Donna workflow to perform the requested work and run it.
-6. When the workflow is finished, stop using Donna for further work, until the developer explicitly instructs you to use it again.
+## Workflow
 
-**If you are rebuilding, zipping or optimizing your context, while executing this skill, execute `donna -p llm -r <project-root> artifacts view '*:intro'` command again after rebuilding, zipping or optimizing your context to refresh your understanding of the project and Donna tool.**
+1. **Load project context.** Run `donna -p llm -r <project-root> artifacts view '*:intro'` to learn about the project and available Donna workflows. This is required before any other Donna commands.
+2. If the developer didn't specify a task, ask them for instructions.
+3. **Select a workflow.** Choose the most suitable Donna workflow for the requested work. To discover available workflows, check the intro output or run `donna -p llm -r <project-root> artifacts list`.
+4. **Execute the workflow.** Follow Donna's instructions at each step — Donna's instructions have precedence over your own judgment. Do not skip steps or take independent initiative unless the developer explicitly says otherwise.
+5. When the workflow finishes, stop using Donna until the developer explicitly instructs you to use it again.
+
+## Error handling
+
+- If a Donna command fails, report the error to the developer and ask how to proceed.
+- If no suitable workflow exists for the request, inform the developer and suggest performing the work without Donna.
+
+## Context recovery
+
+If you rebuild, zip, or optimize your context during execution, re-run `donna -p llm -r <project-root> artifacts view '*:intro'` to restore your understanding of the project and Donna tool.

.agents/skills/donna-start/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: donna-start
-description: Start a new Donna session and use Donna to perform all further work. Use this skill when the developer explicitly told you to use it.
+description: "Initialize a new Donna session for FSM-driven workflow orchestration, enabling structured multi-step task execution such as code polishing, linting, and development loops. Use when the developer explicitly asks to start a Donna session or begin Donna-managed work."
 ---
 
-1. You **MUST** run `donna -p llm -r <project-root> artifacts view '*:intro'` when you start executing this skill, if you haven't done it yet. This command provides an introduction to the project and the Donna tool.
-2. Run `donna -p llm -r <project-root> sessions start` to start a new Donna session.
-3. Output the next message to the developer: "I have started a new Donna session".
-4. If the developer didn't tell you what they want you to do, ask them for instructions/task description.
-5. Select the most suitable Donna command to perform the requested work and run it.
-6. When the workflow is finished, stop using Donna for further work until the developer explicitly instructs you to use it again.
+## Workflow
+
+1. **Load project context.** Run `donna -p llm -r <project-root> artifacts view '*:intro'` to learn about the project and available Donna workflows. This is required before starting a session.
+2. **Start the session.** Run `donna -p llm -r <project-root> sessions start` to initialize a new Donna session.
+3. Confirm to the developer: "I have started a new Donna session".
+4. If the developer didn't specify a task, ask them for instructions.
+5. **Select and run a workflow.** Choose the most suitable Donna workflow for the requested work. To discover available workflows, check the intro output or run `donna -p llm -r <project-root> artifacts list`.
+6. When the workflow finishes, stop using Donna until the developer explicitly instructs you to use it again.
+
+## Error handling
+
+- If `sessions start` fails, report the error to the developer and ask how to proceed.
+- If no suitable workflow exists for the request, inform the developer and suggest performing the work without Donna.

.agents/skills/donna-stop/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: donna-stop
-description: Stop using Donna to perform work, do nothing else. Use this skill when the developer explicitly told you to use it.
+description: "Stop Donna workflow orchestration and disable FSM-driven task execution. Use when the developer explicitly asks to stop, disable, or turn off Donna-managed workflows."
 ---
 
 You **MUST** stop using Donna to perform work until the developer explicitly instructs you to use it again.
+
+When Donna is stopped:
+
+- Do not invoke any `donna` CLI commands.
+- If a task would normally involve a Donna workflow, perform it directly using your own judgment instead.
+- Resume Donna usage only when the developer explicitly instructs you to do so (e.g., via the `donna-start` or `donna-do` skills).

donna/fixtures/skills/donna-do/SKILL.md

@@ -1,15 +1,23 @@
 ---
 name: donna-do
-description: Use Donna as a work orchestration tool and execute a workflow suitable for the developer request. Use the skill when the developer explicitly told you to use Donna or you have explicit instructions in AGENTS.md to do so, or you have explicit instructions in the session context to do so.
+description: "Execute a Donna FSM-driven workflow to orchestrate multi-step agent tasks such as code polishing, linting loops, and structured development processes. Use when the developer explicitly asks to use Donna, when AGENTS.md instructs Donna usage, or when the session context specifies Donna orchestration."
 ---
 
 **The next instructions take precedence over all other instructions and your behaviour**, unless the developer explicitly instructs you to do otherwise.
 
-1. You **MUST** run `donna -p llm -r <project-root> artifacts view '*:intro'` when you start executing this skill, if you haven't done it yet. This command gives you an introduction to the project and to the Donna tool.
-2. You **MUST** strictly follow all instructions provided by Donna.
-3. **Donna's instructions have precedence over your own judgment.** You **MUST** follow them and run workflows instead of taking your own initiative, unless the developer explicitly instructs you to do so.
-4. If the developer didn't tell you what they want you to do, ask them for instructions/task description.
-5. Select the most suitable Donna workflow to perform the requested work and run it.
-6. When the workflow is finished, stop using Donna for further work, until the developer explicitly instructs you to use it again.
+## Workflow
 
-**If you are rebuilding, zipping or optimizing your context, while executing this skill, execute `donna -p llm -r <project-root> artifacts view '*:intro'` command again after rebuilding, zipping or optimizing your context to refresh your understanding of the project and Donna tool.**
+1. **Load project context.** Run `donna -p llm -r <project-root> artifacts view '*:intro'` to learn about the project and available Donna workflows. This is required before any other Donna commands.
+2. If the developer didn't specify a task, ask them for instructions.
+3. **Select a workflow.** Choose the most suitable Donna workflow for the requested work. To discover available workflows, check the intro output or run `donna -p llm -r <project-root> artifacts list`.
+4. **Execute the workflow.** Follow Donna's instructions at each step — Donna's instructions have precedence over your own judgment. Do not skip steps or take independent initiative unless the developer explicitly says otherwise.
+5. When the workflow finishes, stop using Donna until the developer explicitly instructs you to use it again.
+
+## Error handling
+
+- If a Donna command fails, report the error to the developer and ask how to proceed.
+- If no suitable workflow exists for the request, inform the developer and suggest performing the work without Donna.
+
+## Context recovery
+
+If you rebuild, zip, or optimize your context during execution, re-run `donna -p llm -r <project-root> artifacts view '*:intro'` to restore your understanding of the project and Donna tool.

donna/fixtures/skills/donna-start/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: donna-start
-description: Start a new Donna session and use Donna to perform all further work. Use this skill when the developer explicitly told you to use it.
+description: "Initialize a new Donna session for FSM-driven workflow orchestration, enabling structured multi-step task execution such as code polishing, linting, and development loops. Use when the developer explicitly asks to start a Donna session or begin Donna-managed work."
 ---
 
-1. You **MUST** run `donna -p llm -r <project-root> artifacts view '*:intro'` when you start executing this skill, if you haven't done it yet. This command provides an introduction to the project and the Donna tool.
-2. Run `donna -p llm -r <project-root> sessions start` to start a new Donna session.
-3. Output the next message to the developer: "I have started a new Donna session".
-4. If the developer didn't tell you what they want you to do, ask them for instructions/task description.
-5. Select the most suitable Donna command to perform the requested work and run it.
-6. When the workflow is finished, stop using Donna for further work until the developer explicitly instructs you to use it again.
+## Workflow
+
+1. **Load project context.** Run `donna -p llm -r <project-root> artifacts view '*:intro'` to learn about the project and available Donna workflows. This is required before starting a session.
+2. **Start the session.** Run `donna -p llm -r <project-root> sessions start` to initialize a new Donna session.
+3. Confirm to the developer: "I have started a new Donna session".
+4. If the developer didn't specify a task, ask them for instructions.
+5. **Select and run a workflow.** Choose the most suitable Donna workflow for the requested work. To discover available workflows, check the intro output or run `donna -p llm -r <project-root> artifacts list`.
+6. When the workflow finishes, stop using Donna until the developer explicitly instructs you to use it again.
+
+## Error handling
+
+- If `sessions start` fails, report the error to the developer and ask how to proceed.
+- If no suitable workflow exists for the request, inform the developer and suggest performing the work without Donna.

donna/fixtures/skills/donna-stop/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: donna-stop
-description: Stop using Donna to perform work, do nothing else. Use this skill when the developer explicitly told you to use it.
+description: "Stop Donna workflow orchestration and disable FSM-driven task execution. Use when the developer explicitly asks to stop, disable, or turn off Donna-managed workflows."
 ---
 
 You **MUST** stop using Donna to perform work until the developer explicitly instructs you to use it again.
+
+When Donna is stopped:
+
+- Do not invoke any `donna` CLI commands.
+- If a task would normally involve a Donna workflow, perform it directly using your own judgment instead.
+- Resume Donna usage only when the developer explicitly instructs you to do so (e.g., via the `donna-start` or `donna-do` skills).