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

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`.