feat(skills): add python debugpy skill

skills/python-debugpy/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: python-debugpy
+description: Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
+metadata: { "openclaw": { "requires": { "bins": ["python3"] } } }
+---
+
+# Python Debugpy
+
+Use when Python code needs interactive debugging: hidden locals, confusing state mutation, failing tests, subprocesses, long-running services, or remote/headless attach.
+
+Pick the smallest debugger that reaches the bad frame.
+
+## Choose
+
+- `breakpoint()`: local code, source edits ok, fastest path.
+- `python3 -m pdb`: no source edit, launch from the beginning.
+- `python3 -m pdb -c continue`: stop at an unhandled exception.
+- `debugpy`: remote/headless process, DAP client, already-running PID, or service startup race.
+
+## Commands
+
+```bash
+python3 -m pdb path/to/script.py arg1
+python3 -m pdb -c continue path/to/script.py
+python3 -c "import debugpy" || python3 -m pip install debugpy
+python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py
+python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module
+python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>
+```
+
+For source-edit attach:
+
+```py
+import debugpy
+
+debugpy.listen(("127.0.0.1", 5678))
+debugpy.wait_for_client()
+debugpy.breakpoint()
+```
+
+For post-mortem:
+
+```py
+import pdb, sys
+
+try:
+    run()
+except Exception:
+    pdb.post_mortem(sys.exc_info()[2])
+    raise
+```
+
+## pdb
+
+- Flow: `n`, `s`, `r`, `c`, `q`.
+- Stack/source: `w`, `u`, `d`, `a`, `l`, `ll`.
+- Values: `p expr`, `pp expr`, `display expr`.
+- Breakpoints: `b file.py:42`, `b func`, `b file.py:42, condition`, `cl <num>`.
+- Mutate/evaluate: `!statement`; full REPL: `interact`.
+
+## Rules
+
+- Reproduce with the smallest command/test first.
+- Disable parallel test workers for pdb; interactive stdin usually breaks inside worker pools.
+- Keep `debugpy` in the active env; do not add it as a project dependency unless the project already wants it.
+- Bind debug servers to `127.0.0.1`; do not expose `0.0.0.0` unless isolated or tunnelled.
+- Use unique ports for parallel sessions.
+- Treat `debugpy --pid` as injection; avoid security-sensitive or production targets unless explicitly approved.
+- If PID attach fails on Linux, check ptrace/container privileges before changing the target.
+- Cleanup before commit: `rg -n 'breakpoint\\(|pdb\\.set_trace|debugpy\\.' --type py`.
+- Rerun the normal project test/gate without the debugger.
+- `PYTHONBREAKPOINT=0` disables `breakpoint()`.
+- If a process is stuck after debugger detach, confirm it is not still paused at a breakpoint.