@@ -0,0 +1,63 @@
+---
+name: apple-container
+description: Run RustPython tests in Apple's `container` CLI Linux environment. Use when user asks to run or compare Linux test results on macOS.
+allowed-tools: Bash(container:*) Bash(cargo:*) Read Grep Glob
+---
+
+# Run Tests in Linux Container (Apple `container` CLI)
+
+Run RustPython tests inside a Linux container using Apple's `container` CLI.
+NEVER use Docker, Podman, or any other container runtime. Only use the `container` command.
+
+## Arguments
+
+- Test command to run (examples: `test_io`, `test_codecs -v`, `test_io -v -m "test_errors"`)
+
+## Prerequisites
+
+- The `container` CLI is installed via `brew install container`.
+- The dev image `rustpython-dev` is already built.
+
+## Workflow
+
+1. Check whether the test container is already running:
+
+   ```shell
+   container list 2>/dev/null | grep rustpython-test
+   ```
+
+2. Start the container if it is not running:
+
+   ```shell
+   container run -d --name rustpython-test -m 8G -c 4 \
+       --mount type=bind,source="$(pwd)",target=/workspace \
+       -w /workspace rustpython-dev sleep infinity
+   ```
+
+3. Run the requested test command inside the container:
+
+   ```shell
+   container exec rustpython-test cargo run --release -- -m test <test-args>
+   ```
+
+4. Report results:
+
+- Show pass/fail summary and expected failures / unexpected successes.
+- Highlight new failures compared to macOS results, if available.
+- Do not stop or remove the container after testing.
+
+## Notes
+
+- The workspace is bind-mounted, so local code changes are immediately available in the container.
+- Use `container exec rustpython-test sh -c "..."` for any command inside the container.
+- Rebuild after code changes with:
+
+  ```shell
+  container exec rustpython-test sh -c "cargo build --release"
+  ```
+
+- Stop the container when explicitly requested:
+
+  ```shell
+  container rm -f rustpython-test
+  ```
@@ -0,0 +1,53 @@
+---
+name: investigate-test-failure
+description: Investigate a failing RustPython test, compare with CPython behavior, and decide whether to implement a fix or prepare incompatibility issue details.
+allowed-tools: Bash(python3:*) Bash(cargo run:*) Bash(gh issue create:*) Read Grep Glob Bash(git add:*) Bash(git commit:*) Bash(cargo fmt:*) Bash(git diff:*) Task
+---
+
+# Investigate Test Failure
+
+Investigate why a specific test is failing and determine whether it can be fixed now or should be reported as an incompatibility issue.
+
+## Arguments
+
+- Failed test identifier (example: `test_inspect.TestGetSourceBase.test_getsource_reload`)
+
+## Workflow
+
+1. Analyze the failure cause:
+
+- Read the test code.
+- Analyze failure message and traceback.
+- Check related RustPython implementation code.
+
+2. Verify behavior in CPython:
+
+- Run the test with `python3 -m unittest`.
+- Document expected behavior/output.
+
+3. Determine fix feasibility:
+
+- Simple fix (import issues, small logic bugs): implement fix, run formatting and checks, review changes, and commit.
+- Complex fix (major missing feature): gather issue information and report to user.
+
+Pre-commit review process:
+
+- Run `git diff` to review local changes.
+- Use a focused subagent review to compare implementation against CPython behavior and check for missed edge cases.
+- Commit only after review passes.
+
+4. For complex issues, collect issue information using `.github/ISSUE_TEMPLATE/report-incompatibility.md`:
+
+- Feature: missing or broken Python feature.
+- Minimal reproduction code.
+- CPython behavior (`python3`).
+- RustPython behavior (`cargo run`).
+- Python documentation reference link.
+
+Report the collected information to the user. Create an issue only when explicitly requested.
+
+Example issue command:
+
+```shell
+gh issue create --template report-incompatibility.md --title "..." --body "..."
+```
@@ -0,0 +1,34 @@
+---
+name: upgrade-pylib-next
+description: Pick the next CPython stdlib module ready for upgrade based on update_lib todo output and skip modules with open upgrade PRs.
+allowed-tools: Skill(upgrade-pylib) Bash(gh pr list:*) Bash(cargo run:*)
+---
+
+# Upgrade Next Python Library
+
+Find the next Python library module ready for upgrade and then run the `upgrade-pylib` workflow for it.
+
+## Workflow
+
+1. Get current TODO status:
+
+```shell
+cargo run --release -- scripts/update_lib todo 2>/dev/null
+```
+
+2. Get open upgrade PRs:
+
+```shell
+gh pr list --search "Update in:title" --json number,title --template '{{range .}}#{{.number}} {{.title}}{{"\\n"}}{{end}}'
+```
+
+3. From TODO output, select modules in this priority order:
+
+- `[ ] [no deps]`
+- `[ ] [0/n]` where dependencies are all upgraded (for example `[0/3]`, `[0/5]`)
+
+4. Skip modules that already have an open upgrade PR.
+
+5. Run upgrade for selected module using the `upgrade-pylib` workflow.
+
+If no modules match, report that eligible modules are blocked by dependencies.
@@ -0,0 +1,102 @@
+---
+name: upgrade-pylib
+description: Upgrade a Python standard library module from CPython into RustPython using scripts/update_lib and then triage and mark remaining failures.
+allowed-tools: Bash(git add:*) Bash(git commit:*) Bash(git diff:*) Bash(cargo run:*) Bash(python3 scripts/update_lib quick:*) Bash(python3 scripts/update_lib auto-mark:*)
+---
+
+# Upgrade Python Library from CPython
+
+Upgrade a Python standard library module from CPython to RustPython.
+
+## Arguments
+
+- Library name or path (examples: `inspect`, `asyncio`, `json`, `cpython/Lib/inspect.py`, `cpython/Lib/json/`)
+
+## Important: Report Tool Issues First
+
+If `scripts/update_lib` shows a bug, missing automation, or unexpected behavior, stop the upgrade and report the tooling issue first, including:
+
+1. What you were trying to do:
+
+- Library name.
+- Full command used.
+
+2. What went wrong or what is missing.
+3. Expected vs actual behavior.
+
+## Workflow
+
+1. Run quick upgrade with update_lib:
+
+- `python3 scripts/update_lib quick <module>`
+- or `python3 scripts/update_lib quick cpython/Lib/<module>.py`
+- or `python3 scripts/update_lib quick cpython/Lib/<module>/`
+
+This step copies library files, patches tests while preserving markers where possible, runs tests, auto-marks new failures, removes stale `@unittest.expectedFailure`, and creates a commit.
+
+If warnings like `WARNING: TestCFoo does not exist in remote file` appear, class structure changed and some markers must be restored manually.
+
+2. Review diff and restore RustPython-specific changes:
+
+- Run `git diff Lib/test/test_<module>`.
+- Restore only changes with explicit `RUSTPYTHON` comments.
+- Do not restore unrelated upstream CPython changes.
+
+3. Investigate failing dependent tests:
+
+- Get dependencies:
+
+  ```shell
+  cargo run --release -- scripts/update_lib deps <module>
+  ```
+
+- Find direct dependent test modules from the `- [ ] <module>:` line.
+- Run dependent tests and collect failures:
+
+  ```shell
+  cargo run --release -- -m test <test_modules...> 2>&1 | grep -E "^(FAIL|ERROR):"
+  ```
+
+- For each failing test identifier, investigate with the `investigate-test-failure` workflow.
+
+4. Mark remaining failures with auto-mark:
+
+- `python3 scripts/update_lib auto-mark Lib/test/test_<module>.py --mark-failure`
+- or `python3 scripts/update_lib auto-mark Lib/test/test_<module>/ --mark-failure`
+
+Note: `--mark-failure` marks all current failures including regressions; review carefully.
+
+5. Handle panics manually:
+
+- For tests that panic/crash/hang, use `@unittest.skip("TODO: RUSTPYTHON; ...")` rather than expectedFailure.
+
+6. Handle class-specific failures:
+
+- If only one subclass fails (for example `TestCFoo` but not `TestPyFoo`), move marker to the failing subclass override.
+
+7. Commit test-fix markers as a separate commit:
+
+```shell
+git add -u && git commit -m "Mark failing tests"
+```
+
+## Example usage
+
+```text
+upgrade-pylib inspect
+upgrade-pylib json
+upgrade-pylib asyncio
+upgrade-pylib cpython/Lib/inspect.py
+upgrade-pylib cpython/Lib/json/
+```
+
+## Notes
+
+- The `cpython/` directory should contain the CPython source used for sync.
+- `scripts/update_lib` modes:
+  - `quick`: patch + auto-mark
+  - `migrate`: patch only
+  - `auto-mark`: mark failures only
+  - `copy-lib`: copy library files only
+- Patching transfers `@unittest.expectedFailure` and `@unittest.skip` with `TODO: RUSTPYTHON` markers where possible.
+- The tool does not preserve every RustPython-specific change; always review and restore explicit RUSTPYTHON-marked logic.