From 143e902178a07d0f13f9db2308f983aaacaaf0f8 Mon Sep 17 00:00:00 2001 From: Jesse Miller Date: Fri, 4 Sep 2026 13:26:07 -0700 Subject: [PATCH] docs: use organization UUIDs in the skill install reference (#7273) Organization names are not unique, so the documented `@org/name` form can resolve to the wrong organization and fail to find the skill. Document the `@org-uuid/name` form instead, and add a note pointing at `crewai org list` for the UUID. Applies to the agent-side registry refs too: they resolve through the same `/skills/:org/:name` endpoint and the same `~/.crewai/skills/{org}/{name}/` cache path, so leaving them as `@acme` would contradict the install command. Co-authored-by: Claude Opus 5 Co-authored-by: Vidit Ostwal <110953813+Vidit-Ostwal@users.noreply.github.com> --- docs/edge/ar/concepts/skills.mdx | 12 ++++++++---- docs/edge/en/concepts/skills.mdx | 14 +++++++++----- docs/edge/ko/concepts/skills.mdx | 12 ++++++++---- docs/edge/pt-BR/concepts/skills.mdx | 12 ++++++++---- 4 files changed, 33 insertions(+), 17 deletions(-) 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}/`. + + استخدم **UUID** الخاص بمؤسستك وليس اسمها — فأسماء المؤسسات ليست فريدة، وقد يشير الاسم إلى مؤسسة خاطئة فيفشل التثبيت برسالة "غير موجود". شغّل `crewai org list` لعرض الـ UUID (عمود `ID`) لكل مؤسسة تنتمي إليها. + + +داخل مشروع الطاقم تُثبَّت المهارة في `./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}/`. + + 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. + + +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}/`에 저장됩니다. + + 조직 이름이 아니라 조직 **UUID**를 사용하세요 — 조직 이름은 고유하지 않아서 잘못된 조직으로 해석될 수 있고, 그러면 설치가 "찾을 수 없음" 오류로 실패합니다. `crewai org list`를 실행하면 소속된 각 조직의 UUID(`ID` 열)를 확인할 수 있습니다. + + +크루 프로젝트 내부에서는 스킬이 `./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}/`. + + 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. + + +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 ) ```