feat(FN-1810): merge fusion/fn-1810

.changeset/agent-skills-docs.md

@@ -0,0 +1,5 @@
+---
+"@gsxdsm/fusion": patch
+---
+
+Update CLI help text and documentation to describe the agent skill assignment feature. Agent `metadata.skills` now controls execution-time skill injection, taking precedence over role fallback skills.

docs/dashboard-guide.md

@@ -154,6 +154,16 @@ Inspect agents, runtime status, run history, and configuration.
 
 ![Agents view](./screenshots/agents-view.png)
 
+### Agent Skill Assignment
+
+Agents can be assigned skills that determine which capabilities are injected into their sessions at execution time. Skills are configured via the agent's `metadata.skills` field—an array of skill names such as `["review", "executor"]`.
+
+You can set `metadata.skills` in two ways:
+- **Dashboard**: Edit an agent and add or update the `skills` key in its metadata JSON.
+- **Import**: When importing agents from YAML, the `skills` list is mapped to `metadata.skills` automatically.
+
+During task execution, the engine's `buildSessionSkillContext` reads `metadata.skills` from the assigned agent. If valid skills are present, they take **precedence** over the default role fallback skills (e.g., `executor`, `reviewer`, `merger`, `triage`). If no skills are assigned, the engine falls back to the standard role-based skill mapping.
+
 ## Mission Manager
 
 Manage mission hierarchy and progression state.

docs/settings-reference.md

@@ -139,6 +139,8 @@ Defaults from `DEFAULT_PROJECT_SETTINGS`; key scope from `PROJECT_SETTINGS_KEYS`
 | `agentPrompts` | `object` | `undefined` | Custom agent prompt templates + role assignments. |
 | `promptOverrides` | `Record<string, string>` | `undefined` | Fine-grained prompt segment overrides (e.g., `{"executor-welcome": "..."}`). |
 
+> **Note:** Agent `metadata.skills` is not a top-level project setting, but it is the primary mechanism for controlling execution-time skill selection. The engine's `buildSessionSkillContext` function reads this metadata from the assigned agent and uses it to resolve which skills are available in the agent session. If `metadata.skills` is absent or empty, the engine falls back to role-based skills (`executor`, `reviewer`, `merger`, `triage`).
+
 ### Additional ProjectSettings fields
 
 These exist in `ProjectSettings` but are not part of `PROJECT_SETTINGS_KEYS`.

packages/cli/src/bin.ts

@@ -133,6 +133,7 @@ Usage:
                                       Import agents from an Agent Companies package (directory, archive, or AGENTS.md file)
   fn agent export <dir> [--company-name <name>] [--company-slug <slug>]
                                       Export Fusion agents to an Agent Companies package directory
+                                      (agent skills assigned via metadata.skills affect execution-time tools)
   fn agent mailbox <id>             View an agent's mailbox
   fn message inbox                  List inbox messages
   fn message outbox                 List sent messages

packages/cli/src/commands/agent.ts

@@ -33,6 +33,10 @@ async function createAgentStore(projectName?: string): Promise<AgentStore> {
 /**
  * Stop (pause) a running agent.
  * Transitions state from running/active to paused.
+ *
+ * Note: Agent `metadata.skills` (array of skill names) controls which skills
+ * are injected into the agent session at execution time when the agent is
+ * assigned to a task. Skills are resolved by `buildSessionSkillContext`.
  */
 export async function runAgentStop(id: string, projectName?: string): Promise<void> {
   const agentStore = await createAgentStore(projectName);