fix

Author: VascoSch92

sdk/guides/agent-file-based.mdx

@@ -5,6 +5,8 @@ description: Define specialized sub-agents as simple Markdown files with YAML fr
 
 import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx";
 
+> A ready-to-run example is available [here](#ready-to-run-example)!
+
 File-based agents let you define specialized sub-agents using Markdown files. Each file declares the agent's name, description, tools, and system prompt — the same things you'd pass to `register_agent()` in code, but without writing any Python.
 
 This is the fastest way to create reusable, domain-specific agents that can be invoked via [delegation](/sdk/guides/agent-delegation).
@@ -48,7 +50,7 @@ The YAML frontmatter configures the agent. The Markdown body becomes the agent's
 | `description` | No | `""` | What this agent does. Shown to the orchestrator |
 | `tools` | No | `[]` | List of tools the agent can use |
 | `model` | No | `"inherit"` | LLM model (`"inherit"` uses the parent agent's model) |
-| `color` | No | `None` | Display color for the agent |
+| `color` | No | `None` | [Rich color name](https://rich.readthedocs.io/en/stable/appendix/colors.html) (e.g., `"blue"`, `"green"`) used by visualizers to style this agent's output in terminal panels |
 
 ### `<example>` Tags
 
@@ -70,9 +72,9 @@ Place agent files in these directories, scanned in **priority order** (first mat
 | Priority | Location | Scope |
 |----------|----------|-------|
 | 1 | `{project}/.agents/agents/*.md` | Project-level (primary) |
-| 2 | `{project}/.openhands/agents/*.md` | Project-level (legacy) |
+| 2 | `{project}/.openhands/agents/*.md` | Project-level (secondary) |
 | 3 | `~/.agents/agents/*.md` | User-level (primary) |
-| 4 | `~/.openhands/agents/*.md` | User-level (legacy) |
+| 4 | `~/.openhands/agents/*.md` | User-level (secondary) |
 
 <Tree>
     <Tree.Folder name="my-project/" defaultOpen>
@@ -270,7 +272,10 @@ Always include a usage example with expected output when documenting functions o
 
 ## Agents in Plugins
 
-File-based agents can also be bundled inside [plugins](/sdk/guides/plugins). Place them in the `agents/` directory of your plugin:
+> Plugins bundle agents, tools, skills, and MCP servers into reusable packages.
+Learn more about plugins [here](/sdk/guides/plugins).
+
+File-based agents can also be bundled inside plugins. Place them in the `agents/` directory of your plugin:
 
 <Tree>
     <Tree.Folder name="my-plugin/" defaultOpen>