diff --git a/.mintlify/skills b/.mintlify/skills
new file mode 120000
index 000000000..42c5394a1
--- /dev/null
+++ b/.mintlify/skills
@@ -0,0 +1 @@
+../skills
\ No newline at end of file
diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index d8ab10e6f..664e0a59a 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -84,6 +84,29 @@ When you have multiple skills, the `/skill.md` endpoint redirects to the `/.well
   You can use both approaches together with a root `skill.md` file and `.mintlify/skills/` directory. The discovery index includes all skills.
 </Note>
 
+### Use symlinks to avoid duplication
+
+If your skill files live elsewhere in your repository (for example, in a `plugins/` or `skills/` directory), you can symlink `.mintlify/skills` to that location instead of duplicating files:
+
+```bash
+# Skills live in a top-level skills/ directory
+ln -s ../skills .mintlify/skills
+```
+
+```
+project/
+  skills/
+    payments/
+      SKILL.md
+    analytics/
+      SKILL.md
+  .mintlify/
+    skills -> ../skills
+  docs.json
+```
+
+Mintlify resolves symlinks during deployment, so the skill files are discovered and served as if they were directly inside `.mintlify/skills/`. This works with both directory symlinks and individual skill symlinks.
+
 ### Frontmatter fields
 
 Custom `skill.md` files must start with YAML frontmatter.
diff --git a/.mintlify/skills/mintlify-api/SKILL.md b/skills/mintlify-api/SKILL.md
similarity index 100%
rename from .mintlify/skills/mintlify-api/SKILL.md
rename to skills/mintlify-api/SKILL.md
diff --git a/.mintlify/skills/mintlify-docs/SKILL.md b/skills/mintlify-docs/SKILL.md
similarity index 100%
rename from .mintlify/skills/mintlify-docs/SKILL.md
rename to skills/mintlify-docs/SKILL.md