Remove nested python-skills plugin subtree and align docs

.agents/plugins/marketplace.json

@@ -68,7 +68,7 @@
       "name": "python-skills",
       "source": {
         "source": "local",
-        "path": "./plugins/python-skills/plugins/python-skills"
+        "path": "./plugins/python-skills"
       },
       "policy": {
         "installation": "AVAILABLE",

README.md

@@ -140,7 +140,7 @@ Treat `socket` as the canonical home for the monorepo-owned nested directories a
 
 - `agent-plugin-skills`, `dotnet-skills`, `productivity-skills`, `rust-skills`, `things-app`, and `web-dev-skills` are monorepo-owned here.
 - `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` preserve explicit subtree sync paths.
-- Some child repos expose plugin packaging from the repo root, while others keep a nested packaged plugin root inside their own repository tree.
+- Child repos may expose plugin packaging from their own repo roots even when they remain subtree-managed inside `socket`.
 - `things-app` still packages from its child-repo root at `./plugins/things-app`, but its bundled MCP server now lives directly under that child repo's top-level `mcp/` directory rather than under a second nested server folder.
 
 ## Marketplace Shape
@@ -154,7 +154,7 @@ That marketplace points at the actual packaged surface each child repository tre
 - `./plugins/dotnet-skills`
 - `./plugins/productivity-skills`
 - `./plugins/SpeakSwiftlyServer`
-- `./plugins/python-skills/plugins/python-skills`
+- `./plugins/python-skills`
 - `./plugins/rust-skills`
 - `./plugins/things-app`
 - `./plugins/web-dev-skills`

docs/maintainers/subtree-workflow.md

@@ -25,12 +25,10 @@ For `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, when a change
 
 Each nested directory under `plugins/` keeps its own internal layout, docs, and packaging choices.
 
-That means there are two important patterns to expect:
+That means there is one important packaging rule to expect:
 
-1. A child repo may expose plugin packaging at the subtree root.
-   Example: `plugins/agent-plugin-skills/.codex-plugin/plugin.json`
-2. A child repo may keep plugin packaging inside its own nested `plugins/<plugin-name>/` directory.
-   Example: `plugins/python-skills/plugins/python-skills/.codex-plugin/plugin.json`
+1. A child repo exposes plugin packaging from the actual subtree root it treats as installable.
+   Examples: `plugins/agent-plugin-skills/.codex-plugin/plugin.json` and `plugins/python-skills/.codex-plugin/plugin.json`
 
 The socket root marketplace must point at the actual packaged plugin root, not at an assumed one.
 

plugins/python-skills/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "python-skills",
-      "source": "./plugins/python-skills",
+      "source": "./skills",
       "description": "Bundled Python-focused Claude-compatible plugin packaging for uv bootstrapping, FastAPI and FastMCP scaffolding, and pytest workflows."
     }
   ]

plugins/python-skills/AGENTS.md

@@ -1,22 +1,89 @@
 # AGENTS.md
 
-## Repository Role
+Use this file for durable repo-local guidance before changing code, docs, metadata, or packaging in this repository.
 
-- This repository is the canonical source of truth for the shipped Python workflow skills.
-- Treat `productivity-skills` as the default baseline maintainer layer for general repo docs and maintenance work; this repo is the narrower specialist layer when Python-specific behavior should change the workflow.
-- Root `skills/` is the authored workflow surface.
-- [`plugins/python-skills/`](./plugins/python-skills/) is the packaged plugin root used for Codex packaging and should remain a thin packaging layer rather than a second source-of-truth tree.
+## Repository Scope
 
-## Durable Skill Customization
+### What This File Covers
 
-- Global durable customization path for shipped skills: `~/.config/gaelic-ghost/python-skills/<skill-name>/customization.yaml`
-- Repo-local override path: `.codex/profiles/<skill-name>/customization.yaml`
-- Repo-local override files are user-local and must remain untracked.
-- Built-in script defaults remain the canonical fallback when no profile exists or when bypass flags are used.
+- `python-skills` is the canonical source of truth for the shipped Python workflow skills.
+- Root [`skills/`](./skills/) is the authored workflow surface.
+- The repo root is the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json).
+- Treat `productivity-skills` as the default baseline maintainer layer for general repo-doc and maintenance work. Use this repo when Python-specific behavior should materially change the workflow.
 
-## Repo-specific Rules
+### Where To Look First
 
-- Keep direct skill-install guidance accurate alongside plugin installation. Users should be able to install one skill, several skills, or the full bundle from the shared `skills/` tree.
-- Treat each skill's `SKILL.md` plus `agents/openai.yaml` as the canonical per-skill contract pair.
-- Do not reintroduce maintained per-skill `README.md` files unless Gale explicitly restores that public-doc surface.
-- Run repo validation with `uv run scripts/validate_repo_metadata.py` and `uv run pytest` before landing documentation or metadata changes.
+- Start with [`README.md`](./README.md), [`CONTRIBUTING.md`](./CONTRIBUTING.md), and [`ROADMAP.md`](./ROADMAP.md).
+- Use [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md) for the maintained map of the active repo surface.
+- Use [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) when checking whether docs, metadata, and packaging still match shipped reality.
+- Use [`scripts/validate_repo_metadata.py`](./scripts/validate_repo_metadata.py) and [`tests/test_validate_repo_metadata.py`](./tests/test_validate_repo_metadata.py) as the mechanical source of truth for the current metadata contract.
+
+## Working Rules
+
+### Change Scope
+
+- Keep changes focused on one coherent repo outcome.
+- When the shipped skill surface changes, update the affected skill docs, root docs, and packaging metadata in the same pass.
+- Do not broaden this repo into the general-purpose maintainer baseline when the work belongs in `productivity-skills`.
+
+### Source Of Truth
+
+- Treat each skill directory's `SKILL.md` plus `agents/openai.yaml` as the canonical per-skill contract pair.
+- Do not reintroduce a nested packaged plugin subtree for Codex.
+- Do not reintroduce maintained per-skill `README.md` files unless Gale explicitly asks for that public-doc surface again.
+- Keep direct skill-install guidance accurate alongside repo-root plugin guidance.
+
+### Validation Discipline
+
+- Keep user-facing and maintainer-facing Python command examples expressed with `uv`.
+- Run the repo validation path before landing documentation or metadata changes.
+- If docs and validator behavior disagree, update them in the same pass instead of leaving a split-brain repo state.
+
+## Commands
+
+### Setup
+
+```bash
+uv sync --dev
+```
+
+### Validation
+
+```bash
+uv run scripts/validate_repo_metadata.py
+uv run pytest
+```
+
+## Review and Delivery
+
+### Review Expectations
+
+- Explain whether the change affects the authored `skills/` surface, the repo-root plugin metadata, or only repo documentation.
+- Keep install guidance, active skill inventory, and packaging language aligned across root docs and metadata.
+- Prefer small, focused commits over broad mixed maintenance passes.
+
+### Definition Of Done
+
+- The changed surface still preserves root `skills/` as the source of truth.
+- Root docs reflect the current active skill inventory and packaging shape.
+- The repo root still reads as the plugin root for Codex without a second packaged subtree.
+- `uv run scripts/validate_repo_metadata.py` and `uv run pytest` pass when the touched work should affect them.
+
+## Safety Boundaries
+
+### Never Do
+
+- Do not add back a second packaged subtree that duplicates the repo-root plugin surface.
+- Do not invent install paths, marketplace surfaces, or packaging metadata that are not present in the repo.
+- Do not silently widen this repo to own stack-neutral maintainer workflows that belong in `productivity-skills`.
+
+### Ask Before
+
+- Ask before adding a second authored documentation surface for each skill.
+- Ask before changing the packaging split between root `skills/` and repo-root plugin metadata.
+- Ask before introducing new vendor-specific packaging layers beyond the current thin plugin roots.
+
+## Local Overrides
+
+- There are no deeper repo-local `AGENTS.md` files below this root today.
+- If a future nested instruction file is added under a narrower subpath, treat it as refining this root guidance for that subtree.

plugins/python-skills/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to python-skills
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Contribution Workflow](#contribution-workflow)
+- [Local Setup](#local-setup)
+- [Development Expectations](#development-expectations)
+- [Pull Request Expectations](#pull-request-expectations)
+- [Communication](#communication)
+- [Contribution Terms](#contribution-terms)
+
+## Overview
+
+### Who This Guide Is For
+
+Use this guide when you are changing the root docs, packaged plugin metadata, validation helpers, or shipped skills in `python-skills`.
+
+### Before You Start
+
+This repository has a deliberate split between authored workflow content and packaging metadata. Root [`skills/`](./skills/) is the source of truth. The repo root is also the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). Keep that split intact whenever you edit the repo.
+
+## Contribution Workflow
+
+### Choose the Right Surface
+
+Use `python-skills` when Python-, `uv`-, FastAPI-, FastMCP-, or pytest-specific behavior should shape the workflow. If the change is really a general-purpose maintainer pattern, move it to `productivity-skills` instead of broadening this repo.
+
+### Keep Changes Coherent
+
+Keep each change focused on one outcome. When the shipped skill surface changes, update the affected skill docs, packaging metadata, and root inventory docs in the same pass.
+
+### Keep The Docs Split Clean
+
+Use [`README.md`](./README.md) for the public project overview, install surfaces, active skill inventory, and packaging shape. Use this file for maintainer workflow, contributor expectations, and validation habits. Use [`AGENTS.md`](./AGENTS.md) for durable repo-local instructions to Codex.
+
+## Local Setup
+
+### Runtime Config
+
+Sync the maintainer environment before editing docs, metadata, or tests:
+
+```bash
+uv sync --dev
+```
+
+The repo uses [`pyproject.toml`](./pyproject.toml) and [`uv.lock`](./uv.lock) as the maintainer tooling baseline. There is no long-lived service config required for ordinary documentation and metadata work.
+
+### Runtime Behavior
+
+This repository is file-backed rather than service-backed. The normal contributor loop is: edit root `skills/`, keep the repo-root plugin metadata aligned, update the root docs if the shipped surface changed, then run the validation path. For Claude-side local discovery, the repo-root marketplace catalog is `.claude-plugin/marketplace.json`.
+
+## Development Expectations
+
+### Source Of Truth
+
+Treat each skill directory's `SKILL.md` plus `agents/openai.yaml` as the canonical per-skill contract pair. Do not reintroduce a second packaged subtree for Codex, and do not reintroduce maintained per-skill `README.md` files.
+
+### Verification
+
+Run the repo checks before landing documentation or metadata work:
+
+```bash
+uv run scripts/validate_repo_metadata.py
+uv run pytest
+```
+
+When a change touches Python tooling guidance, keep commands expressed with `uv run ...` and make sure the docs still match the real repo surface.
+
+### Accessibility Expectations
+
+Keep contributor-facing and user-facing documentation easy to scan, with clear headings, blunt status text, and packaging language that does not hide which surface is the source of truth. If a docs change affects how people install or discover the repo, make that path explicit.
+
+## Pull Request Expectations
+
+Summarize the real maintainer-facing behavior change, not just the edited files. Call out whether the change affects the authored `skills/` tree, the thin packaging layer, or only the repo docs. Include the validation you ran.
+
+## Communication
+
+Surface scope widening early. If the work starts as a repo-docs pass but actually needs packaging-policy changes, validator changes, or skill-surface changes, say that plainly before continuing.
+
+## Contribution Terms
+
+By contributing to this repository, you agree that your contributions will be licensed under the Apache License 2.0 project license.

plugins/python-skills/README.md

@@ -1,6 +1,6 @@
 # python-skills
 
-Python workflow skills for uv bootstrapping, FastAPI and FastMCP scaffolding, integration work, and pytest setup.
+Python workflow skills for `uv` bootstrapping, FastAPI and FastMCP scaffolding, integration work, and pytest setup.
 
 ## Table of Contents
 
@@ -17,58 +17,85 @@ Python workflow skills for uv bootstrapping, FastAPI and FastMCP scaffolding, in
 
 ## Overview
 
-`python-skills` bundles reusable Python-focused workflows centered on `uv`, FastAPI, FastMCP, and pytest-oriented repo setup.
+`python-skills` is the Python-specific workflow plugin in Gale's skills ecosystem.
 
 ### Status
 
-This repository is active and currently ships authored Python skills, repo-local tests, and a nested packaged plugin root for Codex installation.
+This repository is active and currently ships a focused set of Python workflow skills.
 
 ### What This Project Is
 
-This repository is the canonical source of truth for Gale's Python workflow skills. Root [`skills/`](./skills/) is the authored surface, while the nested packaged plugin root under [`plugins/python-skills/`](./plugins/python-skills/) exists for Codex packaging. Treat `productivity-skills` as the default baseline layer for general repo-doc and maintenance work, and use `python-skills` when Python-, `uv`-, FastAPI-, or FastMCP-specific behavior should shape the workflow.
+This repository is the canonical home for Gale's Python-oriented skill authoring. Root [`skills/`](./skills/) is the authored surface, and the repo root is also the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json).
 
 ### Motivation
 
-It exists to keep Python-specific workflow guidance in one place while preserving a thin packaging layer instead of duplicating the skill tree per platform.
+It exists to keep Python-specific workflow guidance in one place without mixing it into the broader general-purpose maintainer layer owned by `productivity-skills`.
 
 ## Setup
 
-Sync the repo-local maintainer environment before running tests:
+Use the repo-local maintainer environment when you want to inspect, test, or edit this repository:
 
 ```bash
 uv sync --dev
 ```
 
+If you are trying to contribute changes instead of just consume the shipped skills, use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow.
+
 ## Usage
 
-Use this repository when the work is about:
+Use `python-skills` when the work is specifically about:
 
-- bootstrapping uv-managed Python projects or workspaces
-- scaffolding FastAPI or FastMCP services
+- bootstrapping `uv`-managed Python projects or workspaces
+- scaffolding FastAPI services
+- scaffolding FastMCP services
 - integrating FastAPI and FastMCP in one codebase
-- setting up or troubleshooting pytest in uv-managed repos
+- setting up or troubleshooting pytest in `uv`-managed repositories
+
+### Direct Skill Installation
+
+The canonical authored surface is [`skills/`](./skills/). This repository supports direct skill installation from that shared tree into the standard Codex or Claude skill locations when you want one skill or a small subset instead of the whole packaged plugin.
+
+### Packaged Plugin Installation
+
+The Codex plugin root is this repository root. In parent repositories such as `socket`, marketplace entries should point at the child repo root rather than a second nested packaged copy.
+
+### Install-Surface Map
+
+For Codex, keep these surfaces distinct:
+
+- marketplace catalog: a repo marketplace such as `socket/.agents/plugins/marketplace.json` or a personal marketplace at `~/.agents/plugins/marketplace.json`
+- staged plugin directory: this repo root, which is the local plugin payload directory the marketplace entry should point at
+- installed plugin cache: `~/.codex/plugins/cache/$MARKETPLACE_NAME/python-skills/local/`
+- enabled-state config: `~/.codex/config.toml`
+
+For Claude-side discovery, this repo keeps the marketplace catalog at [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json), which points directly at root [`skills/`](./skills/).
+
+### Codex Limitation Warning
+
+OpenAI's documented Codex plugin system supports repo marketplaces, personal marketplaces, staged plugin directories, installed plugin caches, and enabled-state config, but it does not provide proper repo-private plugin scoping beyond that marketplace model.
 
 ## Development
 
 ### Setup
 
-Treat root [`skills/`](./skills/) as the canonical authored surface. Keep the nested packaged plugin root under [`plugins/python-skills/`](./plugins/python-skills/) as install metadata only.
+Treat root [`skills/`](./skills/) as the source of truth for shipped workflow content. Treat [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) as install-surface metadata and discovery wiring, not as second authored trees.
 
 ### Workflow
 
-Update the root skill content first, then keep the nested packaged plugin root, marketplace metadata, and tests aligned in the same pass.
+Keep the public docs, maintainer docs, and packaging metadata aligned in the same pass when the shipped skill surface changes. Use this repository for Python-, `uv`-, FastAPI-, FastMCP-, and pytest-specific workflow behavior. Use `productivity-skills` for broader general-purpose maintainer workflows that should stay stack-neutral.
+
+Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the contributor contract, [`AGENTS.md`](./AGENTS.md) for durable repo-local guidance, and [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md) when you need the deeper maintained map of the active repo surface.
 
 ## Verification
 
-Run the repository test suite before landing metadata or documentation changes:
+Run the repo validation path before landing documentation, metadata, or packaging changes:
 
 ```bash
 uv sync --dev
+uv run scripts/validate_repo_metadata.py
 uv run pytest
 ```
 
-GitHub Actions now mirrors the same maintainer checks on `main` and pull requests by running the repo-metadata validator and test suite.
-
 ## Release Notes
 
 Use Git history and GitHub releases to track shipped changes for this repository.
@@ -87,29 +114,33 @@ See [LICENSE](./LICENSE).
 
 ## Packaging
 
-This repository intentionally separates the authored surface from the packaged plugin root.
+This repository intentionally keeps authored content and plugin metadata separate.
 
 - root [`skills/`](./skills/) is the canonical authored workflow surface
-- [`plugins/python-skills/`](./plugins/python-skills/) is the packaged Codex plugin root used by the `socket` marketplace
-- [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) carries the Claude-side marketplace metadata
+- [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) defines the Codex plugin metadata at the repo root
+- [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) carries the repo-root Claude marketplace catalog
+- [`.claude/skills`](./.claude/skills) is a symlink back to the canonical root skill tree
 
 ## Repository Layout
 
 ```text
 .
+├── .claude/
+│   └── skills -> ../skills
 ├── .claude-plugin/
 │   └── marketplace.json
+├── .codex-plugin/
+│   └── plugin.json
 ├── AGENTS.md
+├── CONTRIBUTING.md
 ├── LICENSE
 ├── README.md
 ├── ROADMAP.md
 ├── docs/
-├── plugins/
-│   └── python-skills/
-│       ├── .claude-plugin/
-│       ├── .codex-plugin/
-│       └── skills -> ../../skills
+│   └── maintainers/
 ├── pyproject.toml
+├── scripts/
+│   └── validate_repo_metadata.py
 ├── skills/
 ├── tests/
 └── uv.lock