You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -140,7 +140,7 @@ Treat `socket` as the canonical home for the monorepo-owned nested directories a
140
140
141
141
-`agent-plugin-skills`, `dotnet-skills`, `productivity-skills`, `rust-skills`, `things-app`, and `web-dev-skills` are monorepo-owned here.
142
142
-`apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` preserve explicit subtree sync paths.
143
-
-Some child repos expose plugin packaging from the repo root, while others keep a nested packaged plugin root inside their own repository tree.
143
+
-Child repos may expose plugin packaging from their own repo roots even when they remain subtree-managed inside `socket`.
144
144
-`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.
145
145
146
146
## Marketplace Shape
@@ -154,7 +154,7 @@ That marketplace points at the actual packaged surface each child repository tre
Use this file for durable repo-local guidance before changing code, docs, metadata, or packaging in this repository.
4
4
5
-
- This repository is the canonical source of truth for the shipped Python workflow skills.
6
-
- 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.
7
-
- Root `skills/` is the authored workflow surface.
8
-
-[`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.
5
+
## Repository Scope
9
6
10
-
##Durable Skill Customization
7
+
### What This File Covers
11
8
12
-
-Global durable customization path for shipped skills: `~/.config/gaelic-ghost/python-skills/<skill-name>/customization.yaml`
-Repo-local override files are user-local and must remain untracked.
15
-
-Built-in script defaults remain the canonical fallback when no profile exists or when bypass flags are used.
9
+
-`python-skills` is the canonical source of truth for the shipped Python workflow skills.
10
+
-Root [`skills/`](./skills/) is the authored workflow surface.
11
+
-The repo root is the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json).
12
+
-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.
16
13
17
-
##Repo-specific Rules
14
+
### Where To Look First
18
15
19
-
- 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.
20
-
- Treat each skill's `SKILL.md` plus `agents/openai.yaml` as the canonical per-skill contract pair.
21
-
- Do not reintroduce maintained per-skill `README.md` files unless Gale explicitly restores that public-doc surface.
22
-
- Run repo validation with `uv run scripts/validate_repo_metadata.py` and `uv run pytest` before landing documentation or metadata changes.
16
+
- Start with [`README.md`](./README.md), [`CONTRIBUTING.md`](./CONTRIBUTING.md), and [`ROADMAP.md`](./ROADMAP.md).
17
+
- Use [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md) for the maintained map of the active repo surface.
18
+
- Use [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) when checking whether docs, metadata, and packaging still match shipped reality.
19
+
- 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.
20
+
21
+
## Working Rules
22
+
23
+
### Change Scope
24
+
25
+
- Keep changes focused on one coherent repo outcome.
26
+
- When the shipped skill surface changes, update the affected skill docs, root docs, and packaging metadata in the same pass.
27
+
- Do not broaden this repo into the general-purpose maintainer baseline when the work belongs in `productivity-skills`.
28
+
29
+
### Source Of Truth
30
+
31
+
- Treat each skill directory's `SKILL.md` plus `agents/openai.yaml` as the canonical per-skill contract pair.
32
+
- Do not reintroduce a nested packaged plugin subtree for Codex.
33
+
- Do not reintroduce maintained per-skill `README.md` files unless Gale explicitly asks for that public-doc surface again.
34
+
- Keep direct skill-install guidance accurate alongside repo-root plugin guidance.
35
+
36
+
### Validation Discipline
37
+
38
+
- Keep user-facing and maintainer-facing Python command examples expressed with `uv`.
39
+
- Run the repo validation path before landing documentation or metadata changes.
40
+
- If docs and validator behavior disagree, update them in the same pass instead of leaving a split-brain repo state.
41
+
42
+
## Commands
43
+
44
+
### Setup
45
+
46
+
```bash
47
+
uv sync --dev
48
+
```
49
+
50
+
### Validation
51
+
52
+
```bash
53
+
uv run scripts/validate_repo_metadata.py
54
+
uv run pytest
55
+
```
56
+
57
+
## Review and Delivery
58
+
59
+
### Review Expectations
60
+
61
+
- Explain whether the change affects the authored `skills/` surface, the repo-root plugin metadata, or only repo documentation.
62
+
- Keep install guidance, active skill inventory, and packaging language aligned across root docs and metadata.
63
+
- Prefer small, focused commits over broad mixed maintenance passes.
64
+
65
+
### Definition Of Done
66
+
67
+
- The changed surface still preserves root `skills/` as the source of truth.
68
+
- Root docs reflect the current active skill inventory and packaging shape.
69
+
- The repo root still reads as the plugin root for Codex without a second packaged subtree.
70
+
-`uv run scripts/validate_repo_metadata.py` and `uv run pytest` pass when the touched work should affect them.
71
+
72
+
## Safety Boundaries
73
+
74
+
### Never Do
75
+
76
+
- Do not add back a second packaged subtree that duplicates the repo-root plugin surface.
77
+
- Do not invent install paths, marketplace surfaces, or packaging metadata that are not present in the repo.
78
+
- Do not silently widen this repo to own stack-neutral maintainer workflows that belong in `productivity-skills`.
79
+
80
+
### Ask Before
81
+
82
+
- Ask before adding a second authored documentation surface for each skill.
83
+
- Ask before changing the packaging split between root `skills/` and repo-root plugin metadata.
84
+
- Ask before introducing new vendor-specific packaging layers beyond the current thin plugin roots.
85
+
86
+
## Local Overrides
87
+
88
+
- There are no deeper repo-local `AGENTS.md` files below this root today.
89
+
- If a future nested instruction file is added under a narrower subpath, treat it as refining this root guidance for that subtree.
Use this guide when you are changing the root docs, packaged plugin metadata, validation helpers, or shipped skills in `python-skills`.
18
+
19
+
### Before You Start
20
+
21
+
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.
22
+
23
+
## Contribution Workflow
24
+
25
+
### Choose the Right Surface
26
+
27
+
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.
28
+
29
+
### Keep Changes Coherent
30
+
31
+
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.
32
+
33
+
### Keep The Docs Split Clean
34
+
35
+
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.
36
+
37
+
## Local Setup
38
+
39
+
### Runtime Config
40
+
41
+
Sync the maintainer environment before editing docs, metadata, or tests:
42
+
43
+
```bash
44
+
uv sync --dev
45
+
```
46
+
47
+
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.
48
+
49
+
### Runtime Behavior
50
+
51
+
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`.
52
+
53
+
## Development Expectations
54
+
55
+
### Source Of Truth
56
+
57
+
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.
58
+
59
+
### Verification
60
+
61
+
Run the repo checks before landing documentation or metadata work:
62
+
63
+
```bash
64
+
uv run scripts/validate_repo_metadata.py
65
+
uv run pytest
66
+
```
67
+
68
+
When a change touches Python tooling guidance, keep commands expressed with `uv run ...` and make sure the docs still match the real repo surface.
69
+
70
+
### Accessibility Expectations
71
+
72
+
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.
73
+
74
+
## Pull Request Expectations
75
+
76
+
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.
77
+
78
+
## Communication
79
+
80
+
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.
81
+
82
+
## Contribution Terms
83
+
84
+
By contributing to this repository, you agree that your contributions will be licensed under the Apache License 2.0 project license.
Copy file name to clipboardExpand all lines: plugins/python-skills/README.md
+54-23Lines changed: 54 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# python-skills
2
2
3
-
Python workflow skills for uv bootstrapping, FastAPI and FastMCP scaffolding, integration work, and pytest setup.
3
+
Python workflow skills for `uv` bootstrapping, FastAPI and FastMCP scaffolding, integration work, and pytest setup.
4
4
5
5
## Table of Contents
6
6
@@ -17,58 +17,85 @@ Python workflow skills for uv bootstrapping, FastAPI and FastMCP scaffolding, in
17
17
18
18
## Overview
19
19
20
-
`python-skills`bundles reusable Python-focused workflows centered on `uv`, FastAPI, FastMCP, and pytest-oriented repo setup.
20
+
`python-skills`is the Python-specific workflow plugin in Gale's skills ecosystem.
21
21
22
22
### Status
23
23
24
-
This repository is active and currently ships authored Python skills, repo-local tests, and a nested packaged plugin root for Codex installation.
24
+
This repository is active and currently ships a focused set of Python workflow skills.
25
25
26
26
### What This Project Is
27
27
28
-
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.
28
+
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).
29
29
30
30
### Motivation
31
31
32
-
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.
32
+
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`.
33
33
34
34
## Setup
35
35
36
-
Sync the repo-local maintainer environment before running tests:
36
+
Use the repo-local maintainer environment when you want to inspect, test, or edit this repository:
37
37
38
38
```bash
39
39
uv sync --dev
40
40
```
41
41
42
+
If you are trying to contribute changes instead of just consume the shipped skills, use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow.
43
+
42
44
## Usage
43
45
44
-
Use this repository when the work is about:
46
+
Use `python-skills`when the work is specifically about:
45
47
46
-
- bootstrapping uv-managed Python projects or workspaces
47
-
- scaffolding FastAPI or FastMCP services
48
+
- bootstrapping `uv`-managed Python projects or workspaces
49
+
- scaffolding FastAPI services
50
+
- scaffolding FastMCP services
48
51
- integrating FastAPI and FastMCP in one codebase
49
-
- setting up or troubleshooting pytest in uv-managed repos
52
+
- setting up or troubleshooting pytest in `uv`-managed repositories
53
+
54
+
### Direct Skill Installation
55
+
56
+
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.
57
+
58
+
### Packaged Plugin Installation
59
+
60
+
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.
61
+
62
+
### Install-Surface Map
63
+
64
+
For Codex, keep these surfaces distinct:
65
+
66
+
- marketplace catalog: a repo marketplace such as `socket/.agents/plugins/marketplace.json` or a personal marketplace at `~/.agents/plugins/marketplace.json`
67
+
- staged plugin directory: this repo root, which is the local plugin payload directory the marketplace entry should point at
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/).
72
+
73
+
### Codex Limitation Warning
74
+
75
+
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.
50
76
51
77
## Development
52
78
53
79
### Setup
54
80
55
-
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.
81
+
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.
56
82
57
83
### Workflow
58
84
59
-
Update the root skill content first, then keep the nested packaged plugin root, marketplace metadata, and tests aligned in the same pass.
85
+
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.
86
+
87
+
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.
60
88
61
89
## Verification
62
90
63
-
Run the repository test suite before landing metadata or documentation changes:
91
+
Run the repo validation path before landing documentation, metadata, or packaging changes:
64
92
65
93
```bash
66
94
uv sync --dev
95
+
uv run scripts/validate_repo_metadata.py
67
96
uv run pytest
68
97
```
69
98
70
-
GitHub Actions now mirrors the same maintainer checks on `main` and pull requests by running the repo-metadata validator and test suite.
71
-
72
99
## Release Notes
73
100
74
101
Use Git history and GitHub releases to track shipped changes for this repository.
@@ -87,29 +114,33 @@ See [LICENSE](./LICENSE).
87
114
88
115
## Packaging
89
116
90
-
This repository intentionally separates the authored surface from the packaged plugin root.
117
+
This repository intentionally keeps authored content and plugin metadata separate.
91
118
92
119
- root [`skills/`](./skills/) is the canonical authored workflow surface
93
-
-[`plugins/python-skills/`](./plugins/python-skills/) is the packaged Codex plugin root used by the `socket` marketplace
94
-
-[`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) carries the Claude-side marketplace metadata
120
+
-[`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) defines the Codex plugin metadata at the repo root
121
+
-[`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) carries the repo-root Claude marketplace catalog
122
+
-[`.claude/skills`](./.claude/skills) is a symlink back to the canonical root skill tree
0 commit comments