Document upstream Codex skill catalog policy

Author: RichardGeorgeDavis

README.md

@@ -153,6 +153,13 @@ See:
 - [docs/06-cross-agent-skills-and-mcp.md](docs/06-cross-agent-skills-and-mcp.md)
 - [docs/07-context-cache-and-retrieval.md](docs/07-context-cache-and-retrieval.md)
 
+External skill catalogs such as [`openai/skills`](https://github.com/openai/skills) should be treated as optional upstream sources for Codex skills, not vendored workspace dependencies.
+
+- install only the specific skills that solve a real workflow need
+- prefer local skill installation via Codex tooling such as `$skill-installer`
+- keep workspace-specific skills in tracked portable folders such as `shared/skills/` or repo-local `.workspace/skills/`
+- do not add the whole upstream skill catalog to `repos/`, `tools/`, or as a submodule unless there is a very specific maintenance reason
+
 ## Community
 
 - Ask questions in [GitHub Discussions Q&A](https://github.com/RichardGeorgeDavis/Codex-Workspace/discussions/categories/q-a)

docs/06-cross-agent-skills-and-mcp.md

@@ -23,6 +23,13 @@ Do not make `.agents/skills/`, `.claude/skills/`, `.github/skills/`, or any simi
 
 Treat those folders as compatibility targets that can be generated, symlinked, or copied from a portable source when a given tool needs them.
 
+Treat upstream skill catalogs such as [`openai/skills`](https://github.com/openai/skills) the same way:
+
+- use them as optional source material for selected Codex skills
+- install specific skills when they are useful
+- do not vendor the whole catalog into this workspace by default
+- keep canonical workspace skill content in `shared/skills/` or repo-local `.workspace/skills/`
+
 ## Minimal layout
 
 ```text
@@ -155,6 +162,8 @@ That means:
 - keep generated adapter folders local unless there is a strong reason to publish them
 - if the adapter target lives inside a repo, let that repo decide whether to ignore or publish it
 
+If you need a skill from an upstream catalog, prefer installing that one skill through the agent's supported installer flow rather than copying the upstream repository into `repos/` or `tools/`.
+
 ## MCP rule
 
 Skills are portable documentation plus workflow packaging.

docs/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026-03-22
+
+- Clarified that upstream skill catalogs such as `openai/skills` should be treated as optional sources for selected Codex skills rather than vendored workspace dependencies.
+- Added matching guidance in the root README, the cross-agent skills and MCP note, and the Workspace Hub extension guide.
+
 ## 2026-03-21
 
 - Added GitHub Discussions support links so repository questions are routed toward Discussions Q&A instead of Issues.

repos/workspace-hub/docs/skills.md

@@ -16,6 +16,12 @@ Good public guidance includes:
 
 If you use a local assistant or agent setup, keep machine-specific skill lists and private workflow notes in ignored `*.local.md` files instead of tracked docs.
 
+If you use upstream skill catalogs such as [`openai/skills`](https://github.com/openai/skills), treat them as optional sources for selected skills rather than as something to vendor into this repo or the wider workspace.
+
+- install only the skills that solve a real workflow problem
+- prefer the agent's supported installer flow
+- keep repo-owned guidance in tracked portable locations such as `.workspace/skills/`
+
 ## Good extension candidates
 
 - workspace maintenance and Git hygiene