diff --git a/docs/edge/ar/concepts/skills.mdx b/docs/edge/ar/concepts/skills.mdx
index faef071d3..924e4005b 100644
--- a/docs/edge/ar/concepts/skills.mdx
+++ b/docs/edge/ar/concepts/skills.mdx
@@ -202,13 +202,17 @@ crewai skill publish
 
 ### التثبيت
 
-ثبّت مهارة منشورة عبر مرجعها `@org/name`:
+ثبّت مهارة منشورة عبر مرجعها `@org-uuid/name`:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-داخل مشروع الطاقم تُثبَّت المهارة في `./skills/{name}/`؛ وخارج المشروع تذهب إلى ذاكرة التخزين المؤقتة المشتركة في `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  استخدم **UUID** الخاص بمؤسستك وليس اسمها — فأسماء المؤسسات ليست فريدة، وقد يشير الاسم إلى مؤسسة خاطئة فيفشل التثبيت برسالة "غير موجود". شغّل `crewai org list` لعرض الـ UUID (عمود `ID`) لكل مؤسسة تنتمي إليها.
+</Note>
+
+داخل مشروع الطاقم تُثبَّت المهارة في `./skills/{name}/`؛ وخارج المشروع تذهب إلى ذاكرة التخزين المؤقتة المشتركة في `~/.crewai/skills/{org-uuid}/{name}/`.
 
 يمكن للوكلاء أيضًا الإشارة إلى مهارات السجل مباشرة — يتم حلّها من ذاكرة التخزين المؤقتة المحلية (أو من مجلد `skills/` في المشروع) وقت التشغيل:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 
diff --git a/docs/edge/en/concepts/skills.mdx b/docs/edge/en/concepts/skills.mdx
index 66960edb4..402dfdea9 100644
--- a/docs/edge/en/concepts/skills.mdx
+++ b/docs/edge/en/concepts/skills.mdx
@@ -210,13 +210,17 @@ Publishing reads `name`, `description`, and `metadata.version` from the `SKILL.m
 
 ### Install
 
-Install a published skill by its `@org/name` reference:
+Install a published skill by its `@org-uuid/name` reference:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-Inside a crew project the skill lands in `./skills/{name}/`; outside a project it goes to the shared cache at `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  Use your organization's **UUID**, not its name — organization names are not unique, so a name can resolve to the wrong organization and the install fails with a "not found" error. Run `crewai org list` to see the UUID (the `ID` column) of every organization you belong to.
+</Note>
+
+Inside a crew project the skill lands in `./skills/{name}/`; outside a project it goes to the shared cache at `~/.crewai/skills/{org-uuid}/{name}/`.
 
 Agents can also reference registry skills directly — they resolve from the local cache (or project `skills/` directory) at runtime:
 
@@ -225,7 +229,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 
@@ -240,7 +244,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review@1.2.0"],  # pinned; a leading "v" also works
+    skills=["@your-org-uuid/code-review@1.2.0"],  # pinned; a leading "v" also works
 )
 ```
 
diff --git a/docs/edge/ko/concepts/skills.mdx b/docs/edge/ko/concepts/skills.mdx
index 1bf4e881f..67402fd2a 100644
--- a/docs/edge/ko/concepts/skills.mdx
+++ b/docs/edge/ko/concepts/skills.mdx
@@ -202,13 +202,17 @@ crewai skill publish
 
 ### 설치
 
-게시된 스킬을 `@org/name` 참조로 설치합니다:
+게시된 스킬을 `@org-uuid/name` 참조로 설치합니다:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-크루 프로젝트 내부에서는 스킬이 `./skills/{name}/`에 설치되고, 프로젝트 외부에서는 공유 캐시인 `~/.crewai/skills/{org}/{name}/`에 저장됩니다.
+<Note>
+  조직 이름이 아니라 조직 **UUID**를 사용하세요 — 조직 이름은 고유하지 않아서 잘못된 조직으로 해석될 수 있고, 그러면 설치가 "찾을 수 없음" 오류로 실패합니다. `crewai org list`를 실행하면 소속된 각 조직의 UUID(`ID` 열)를 확인할 수 있습니다.
+</Note>
+
+크루 프로젝트 내부에서는 스킬이 `./skills/{name}/`에 설치되고, 프로젝트 외부에서는 공유 캐시인 `~/.crewai/skills/{org-uuid}/{name}/`에 저장됩니다.
 
 에이전트는 레지스트리 스킬을 직접 참조할 수도 있습니다 — 런타임에 로컬 캐시(또는 프로젝트 `skills/` 디렉터리)에서 해석됩니다:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 
diff --git a/docs/edge/pt-BR/concepts/skills.mdx b/docs/edge/pt-BR/concepts/skills.mdx
index 09418ae65..8d51cceef 100644
--- a/docs/edge/pt-BR/concepts/skills.mdx
+++ b/docs/edge/pt-BR/concepts/skills.mdx
@@ -202,13 +202,17 @@ A publicação lê `name`, `description` e `metadata.version` do frontmatter do
 
 ### Instalar
 
-Instale uma skill publicada pela sua referência `@org/name`:
+Instale uma skill publicada pela sua referência `@org-uuid/name`:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-Dentro de um projeto de crew, a skill é colocada em `./skills/{name}/`; fora de um projeto, vai para o cache compartilhado em `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  Use o **UUID** da sua organização, não o nome — nomes de organização não são únicos, então um nome pode resolver para a organização errada e a instalação falha com um erro de "não encontrado". Execute `crewai org list` para ver o UUID (a coluna `ID`) de cada organização à qual você pertence.
+</Note>
+
+Dentro de um projeto de crew, a skill é colocada em `./skills/{name}/`; fora de um projeto, vai para o cache compartilhado em `~/.crewai/skills/{org-uuid}/{name}/`.
 
 Agentes também podem referenciar skills do registro diretamente — elas são resolvidas a partir do cache local (ou do diretório `skills/` do projeto) em tempo de execução:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```