Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "cpython-skills",
+  "description": "Skills for working with the CPython repository - helping with building, testing, and contributing to Python's implementation",
+  "version": "0.0.0-2025.11.28",
+  "author": {
+    "name": "CPython Core Team",
+    "email": "zhongweili@tubi.tv"
+  },
+  "skills": [
+    "./skills"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# cpython-skills
+
+Skills for working with the CPython repository - helping with building, testing, and contributing to Python's implementation

plugin.lock.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:gpshead/cpython-skills:plugins/cpython-skills",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "0fc95fbbcf29ea8fe65548ac64636cafeb4fb2ff",
+    "treeHash": "43aa7dbeba91e7fcccedb3883aa950731c92cb8b0283f32618bd9b09be788acb",
+    "generatedAt": "2025-11-28T10:17:02.304055Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "cpython-skills",
+    "description": "Skills for working with the CPython repository - helping with building, testing, and contributing to Python's implementation",
+    "version": null
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "46b283bebd539fc5a41410ec83b51f9003c1117f12012401d44d6ca4fc31069e"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "b94634f899336ca59c8dac38891bf235c1d4ced4dc661b5712bba87bb44de375"
+      },
+      {
+        "path": "skills/cpython-build/SKILL.md",
+        "sha256": "825642ea6c470ee9dd2599298c5b758aa57b4baa2508ea8dea7b4efd05a9bb9f"
+      },
+      {
+        "path": "skills/cpython-context/SKILL.md",
+        "sha256": "e7c0fd9ef60a04e51f391a3e862db7c279d911537f8dde10ab4531531a19cf26"
+      },
+      {
+        "path": "skills/cpython-code-style/SKILL.md",
+        "sha256": "75fdfc2e861b1b4db4d6532f32c6db97b12ac68de47efedbbb8f8e586ce89519"
+      },
+      {
+        "path": "skills/cpython-testing/SKILL.md",
+        "sha256": "68fccd17f30a64eb6b83cd59d1e746f8e977b5b5006db318de7213ec615de7d7"
+      },
+      {
+        "path": "skills/cpython-navigation/SKILL.md",
+        "sha256": "49744afe0d7fcb03a81b708dd26625bd95d666e023853c80d610d0e1d140db7a"
+      }
+    ],
+    "dirSha256": "43aa7dbeba91e7fcccedb3883aa950731c92cb8b0283f32618bd9b09be788acb"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/cpython-build/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: cpython-build
+description: Use this skill when you need to configure, build, or rebuild CPython from source. It covers initial setup with configure, incremental builds, platform-specific considerations, and working with Argument Clinic generated code.
+---
+
+# Building CPython
+
+**ONLY build in a `build/` subdirectory** at repo root. Never build in the source tree.
+
+## Setup and Configuration
+
+**IMPORTANT**: Use sub-agents when running configure and make build steps!
+
+```bash
+# Build directory setup
+REPO_ROOT=<path-to-cpython-git-repo>
+BUILD_DIR=$REPO_ROOT/build
+
+# Configure with debug support (enables debug symbols, assertions, runtime checks)
+cd $BUILD_DIR && ../configure --with-pydebug
+
+# Build using all CPU cores (initial or incremental)
+make -C $BUILD_DIR -j $(nproc)
+```
+
+**Platform notes**:
+- Linux: `BUILT_PY=$BUILD_DIR/python`
+- macOS: `BUILT_PY=$BUILD_DIR/python.exe` (note .exe extension)
+- Windows: Ask user how to build (uses Visual Studio, different process)
+
+## Argument Clinic
+
+After editing `.c` files that change function signatures, docstrings, or argument specs:
+```bash
+make -C $BUILD_DIR clinic
+```
+
+**NEVER** edit files in `**/clinic/**` subdirectories - they're auto-generated.
+
+## Verify Build
+
+```bash
+$BUILT_PY --version
+$BUILT_PY -c "print('Hello from CPython!')"
+```
+
+## Troubleshooting
+
+- **Missing dependencies**: Configure reports missing libraries
+- **Stale build**: `make clean` in BUILD_DIR and rebuild
+- **Clinic files out of sync**: `make -C $BUILD_DIR clinic`
+- **Clean build**: `rm -rf $BUILD_DIR && mkdir $BUILD_DIR && cd $BUILD_DIR && ../configure --with-pydebug && make -C $BUILD_DIR -j $(nproc)`

skills/cpython-code-style/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: cpython-code-style
+description: Use this skill when writing or modifying CPython code to ensure it follows proper coding standards (PEP 7 for C, PEP 8 for Python), formatting rules, linting requirements, and pre-commit checks. It covers whitespace handling, type annotations policy, and documentation formatting.
+---
+
+# CPython Coding Style and Standards
+
+## Style Guidelines
+
+**Python code** (`Lib/` etc): Follow PEP 8. Be consistent with nearby code.
+
+**C code** (`Modules/`, `Objects/`, `Python/`, `Include/`): Follow PEP 7. Be consistent with nearby code.
+
+## Critical Rules
+
+**NEVER leave trailing whitespace on any line.** Pre-commit hooks will catch this.
+
+**ALWAYS preserve the final newline** at the end of files.
+
+**NEVER add type annotations to `Lib/` tree.** Stdlib doesn't use inline annotations (maintained in typeshed separately). Annotations may be OK in `Tools/` or test code if requested.
+
+**No autoformatting by default.** Only use `Doc/venv/bin/ruff format` if explicitly requested.
+
+## Pre-Commit Workflow
+
+Before committing, run from repo root:
+
+```bash
+# 1. Pre-commit hooks (checks whitespace, file endings, syntax)
+pre-commit run --all-files
+
+# 2. Patchcheck (MUST PASS - validates C/Python style, docs, whitespace)
+make -C $BUILD_DIR patchcheck
+
+# 3. If you modified Doc/, verify reStructuredText
+make -C Doc check
+
+# 4. Run relevant tests
+$BUILT_PY -m test test_yourmodule -j $(nproc)
+```
+
+## Documentation
+
+- **Python docstrings**: Follow PEP 257, document params/returns/exceptions
+- **C comments**: Follow PEP 7, document complex algorithms
+- **reStructuredText** (`Doc/`): Follow Sphinx/reST conventions, verify with `make -C Doc check`

skills/cpython-context/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cpython-context
+description: Use this skill when working in the CPython repository. It provides essential context about the CPython codebase, recommended tools, and best practices for maintaining engineering notebooks while working on Python runtime and standard library development.
+---
+
+# CPython Context
+
+You are working in the CPython repository - the implementation of the Python language runtime and standard library itself.
+
+## Recommended Tools
+
+Prefer these tools when available:
+- **`rg` (ripgrep)**: Use instead of `grep` or `find` for faster searching
+- **`gh` (GitHub CLI)**: Get PR/issue info, use GraphQL API when needed
+- **`jq`**: Process JSON responses
+- **`pre-commit`**: Run code quality checks
+
+## File Size Considerations
+
+Source files can be **very long**. Check file sizes before reading entire files - consider reading specific sections or searching instead.
+
+## Engineering Notebooks
+
+ALWAYS load and maintain notebooks when working on features or PRs:
+- **For PRs**: `.claude/pr-{PR_NUMBER}.md`
+- **For branches**: `.claude/branch-{branch_name_without_slashes}.md` (when not on `main`)
+
+Keep notebooks updated with learnings and project state as you work and after commits. Include: problem statement, key findings, file locations, design decisions, testing strategy, and status.
+
+## Optional Developer Resources
+
+- **Developer Guide**: If `REPO_ROOT/../devguide/` exists, see `developer-workflow/` and `documentation/` subdirectories
+- **PEPs**: May exist in `REPO_ROOT/../peps/` tree - reference relevant PEPs when working on changes

skills/cpython-navigation/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cpython-navigation
+description: Use this skill when you need to understand the CPython source code structure, find where specific functionality is implemented (C runtime, stdlib, tests, docs), or understand the relationship between different parts of the codebase like modules and their tests.
+---
+
+# CPython Source Code Navigation
+
+## Source Code Structure
+
+**`Lib/`** - Python standard library (pure Python). Example: `Lib/zipfile.py`
+
+**`Modules/`** - C extension modules for performance/low-level access. Example: `Modules/_csv.c`
+
+**`Objects/` and `Python/`** - Core types (list, dict, int), builtins, runtime, interpreter loop
+
+**`Include/`** - C header files for public and internal C APIs
+
+**`Lib/test/`** - All unittests
+- Test naming: `test_{module_name}.py` or `test_{module_name}/`
+- Examples: `Lib/zipfile.py` → `Lib/test/test_zipfile**`, `Modules/_csv.c` → `Lib/test/test_csv.py`
+- Test packages require `load_tests()` in `test_package/__init__.py` to work with `python -m test`
+
+**`Doc/`** - Documentation in .rst format (source for python.org docs), builds to `Doc/build/`
+
+**`InternalDocs/`** - Maintainer documentation (`InternalDocs/README.md` is the starting point)
+
+**`Tools/`** - Build tools like Argument Clinic, development utilities
+
+## Argument Clinic
+
+Generates C boilerplate for argument parsing from specially formatted comments in `.c` files. Output goes to `**/clinic/**` subdirectories.
+
+**NEVER edit files in `**/clinic/**` subdirectories** - they're auto-generated! Edit the source `.c` file, then run `make -C BUILD_DIR clinic`.
+
+## Scratch Space
+
+**NEVER create throwaway files in repo root.** Use `.claude/sandbox/` for exploration files, test scripts, and prototypes.

skills/cpython-testing/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: cpython-testing
+description: Use this skill when you need to run CPython tests, whether running individual test files, specific test cases, the full test suite, or collecting code coverage. It covers unittest-based testing (not pytest), debugging tests, and test best practices.
+---
+
+# Running CPython Tests
+
+**Critical rules:**
+1. **ALWAYS use sub-agents when running tests**
+2. **NEVER use `pytest`** - CPython tests are `unittest` based
+3. **Use `--match` not `-k`** for filtering (this is not pytest!)
+
+Prerequisite: `BUILT_PY=build/python` or `build/python.exe`
+
+## Running Tests
+
+```bash
+# Single test module (recommended - proper discovery, parallel execution)
+$BUILT_PY -m test test_zipfile -j $(nproc)
+
+# Multiple modules
+$BUILT_PY -m test test_csv test_json -j $(nproc)
+
+# Direct execution (quick but may miss test packages)
+$BUILT_PY Lib/test/test_csv.py
+
+# Specific test pattern (use --match, NOT -k!)
+$BUILT_PY -m test test_zipfile --match "*large*" -j $(nproc)
+$BUILT_PY -m test test_csv --match "TestDialect*"
+$BUILT_PY -m test test_json --match "TestEncode.test_encode_string"
+
+# Full test suite (ASK FIRST - takes significant time!)
+make -C $BUILD_DIR test
+
+# Useful flags: -v (verbose), -f (fail fast), --list-tests (show all), --help
+```
+
+**Test packages** (directories like `test_asyncio/`) require `load_tests()` in `__init__.py` to work with `python -m test`.
+
+## Code Coverage
+
+```bash
+# Collect coverage (uses trace mechanism via libregrtest)
+$BUILT_PY -m test --coverage test_csv test_json --coveragedir .claude/coverage/ -j $(nproc)
+
+# Reports go to specified coveragedir
+```
+
+## Debugging
+
+For interactive debugging (pdb/lldb/gdb) or testing REPL features: **Control a tmux session**.
+
+Add `breakpoint()` in test code, then run with `-v` for verbose output.