diff --git a/apps/docs/src/content/docs/api/agent-api.md b/apps/docs/src/content/docs/api/agent-api.md
index a1524b4f..bbe6b604 100644
--- a/apps/docs/src/content/docs/api/agent-api.md
+++ b/apps/docs/src/content/docs/api/agent-api.md
@@ -118,7 +118,7 @@ type Skill =
     };
 ```
 
-Skill metadata registered with an agent, harness, or profile. Imported `SkillReference` values bundle application-owned skill content. Inline metadata adds only a named catalog entry; it does not package or inject an instruction body. Initialization rejects a registered skill whose name collides with a workspace-discovered skill. See [Skills](/docs/guide/skills/).
+Skill metadata registered with an agent, harness, or profile. Imported `SkillReference` values bundle application-owned skill content. Inline metadata adds only a named catalog entry: it is visible in the skill catalog, but it does not package `SKILL.md`, inject instructions, or load supporting files. Use imported or workspace-discovered skills when you need reusable behavior. Initialization rejects a registered skill whose name collides with a workspace-discovered skill. See [Skills](/docs/guide/skills/).
 
 ## `defineTool(...)`
 
diff --git a/apps/docs/src/content/docs/guide/skills.md b/apps/docs/src/content/docs/guide/skills.md
index c13405d9..f4884c14 100644
--- a/apps/docs/src/content/docs/guide/skills.md
+++ b/apps/docs/src/content/docs/guide/skills.md
@@ -73,6 +73,8 @@ Each discovered skill is available by its declared name without a TypeScript imp
 
 If an imported skill registered on an agent and a discovered workspace skill declare the same name, initialization fails rather than choosing one implicitly.
 
+Flue also accepts inline skill metadata in `skills: [{ name, description }]`, but that form only registers a catalog entry. It does not package `SKILL.md`, and it does not inject reusable skill instructions or supporting files. Use imported skills or workspace-discovered skills when you want real reusable behavior.
+
 ## Frontmatter support
 
 Flue validates every `SKILL.md` against the [Agent Skills specification](https://agentskills.io/specification), whether the skill is imported or discovered in a workspace. The table below lists Flue's support level for each frontmatter field: