菜单
Build, install, run and drive the opossum CLI. Use when asked to run opossum, start it, try a command, smoke test it, reproduce CLI behaviour, verify a change works end to end, or run its tests.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/yamz8/opossum --skill run-opossum命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | run-opossum |
| description | Build, install, run and drive the opossum CLI. Use when asked to run opossum, start it, try a command, smoke test it, reproduce CLI behaviour, verify a change works end to end, or run its tests. |
opossum is a zero-dependency Python CLI that rewrites an awesome list's
README.md in place. There is no server, no UI and nothing to screenshot: what
you observe is the exit code, the stdout, and how the markdown file
changed. Drive all three with
.claude/skills/run-opossum/driver.py, which builds a throwaway list in a temp
directory and runs the real binary against it.
None. No system packages were needed in this container — python3 -m venv
worked out of the box, and opossum has no runtime dependencies (standard
library only, Python 3.9+).
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/opossum --version
# → opossum 0.1.0
.venv/ is already gitignored. The editable install points at the source tree,
so edits to opossum/*.py take effect with no reinstall.
You can skip setup entirely. The driver falls back to
python3 -m opossum (with PYTHONPATH set to the repo) when no opossum is
on PATH, so it runs against a bare clone.
python3 .claude/skills/run-opossum/driver.py
# → driving: /usr/local/bin/python3 -m opossum
# list: /tmp/opossum-drive-w3rblpml/README.md
#
# ok — 29 checks passed
Against the installed binary, with the model exercised directly too:
python3 .claude/skills/run-opossum/driver.py --bin .venv/bin/opossum --library
# → library ok: 2 entries, 3 sections
# ok — 30 checks passed
| flag | what it does |
|---|---|
| (none) | Full CLI lifecycle: init, rm, section add, add ×2, dry run, fmt/toc/lint --check, damage-and-repair, ls --json, stats |
--bin PATH | Which opossum to drive. Default: opossum on PATH, else python3 -m opossum |
--library | Import the model and edit a document without the CLI — the layer most changes touch |
--network | Also run the link checker against a reachable and a 404 URL |
--keep | Leave the scratch list on disk and print its path, so you can poke it by hand |
The driver asserts exit codes and file content, so it catches behaviour the
test suite would not. Breaking alphabetical insertion in edit.py, for
instance, produces:
FAILED — 3 of 29 checks:
a new entry was not inserted in alphabetical position
`opossum lint --strict` exited 1, expected 0 — 0 error(s), 1 warning(s)
To poke a real list yourself:
python3 .claude/skills/run-opossum/driver.py --keep
# → kept: /tmp/opossum-drive-i8gxj03c
cd /tmp/opossum-drive-i8gxj03c && /home/user/opossum/.venv/bin/opossum ls
Every command walks up from the working directory to find README.md, so work
inside a list directory (or pass --path):
OPOSSUM=$PWD/.venv/bin/opossum
cd "$(mktemp -d)"
$OPOSSUM init "Awesome Possums" --description "Everything about possums."
$OPOSSUM add "Alpha" https://alpha.example -d "The first one."
$OPOSSUM lint
# → no issues found
Exit codes are the contract: 0 clean, 1 the check failed (lint errors,
fmt --check needs changes, broken links), 2 you asked for something
impossible (unknown section, duplicate URL, missing file).
Same binary, no driver: opossum init, opossum add …, opossum lint. See
README.md for the full command reference. Nothing is interactive and nothing
long-running, so there is no process to stop.
python3 -m unittest discover
# → Ran 131 tests in 1.218s / OK
python3 tools/check.py --fuzz 500
# → all 4 checks passed in 4.3s
tools/check.py is the project's real gate (tests + corpus + fuzzing + its own
end-to-end CLI run). The driver here is complementary: the gate proves the
invariants hold, the driver proves the installed command behaves.
opossum lint inside this repo lints opossum's own README and exits 1
with 2 error(s), 3 warning(s). That is correct behaviour, not a bug: the
project README is not an awesome list, and the command walks up from the
working directory to the nearest README.md. Always cd into a scratch list
before trying commands by hand. This trap is why the driver builds its own
list in a temp directory.opossum check cannot succeed in this container. The egress proxy
refuses most hosts, so the scaffolded https://example.com entry returns
Tunnel connection failed: 403 Forbidden and the command reports
0/1 links ok and exits 1. The link checker is fine — the network is
filtered. pypi.org and raw.githubusercontent.com are reachable, which is
what driver.py --network uses to test it positively (200 vs 404).--fetch and enrich silently degrade here. api.github.com is blocked,
so opossum add <repo-url> --fetch prints
warning: could not read owner/repo from GitHub, then still adds the entry
using the repo name from the URL and no description. Exit code stays 0. Do
not read that as the fetch feature being broken.--bin needs the driver's resolution. Commands run with the
scratch list as their working directory, so --bin .venv/bin/opossum is
resolved to an absolute path first. Passing a relative path to any other tool
that runs commands elsewhere will fail with FileNotFoundError.python3 -m opossum needs PYTHONPATH when its working directory is not
the repo. The driver sets it; if you invoke the module yourself from a list
directory, export PYTHONPATH=/home/user/opossum or use the venv binary.FileNotFoundError: '.venv/bin/opossum' from the driver: you passed a
relative --bin to an older copy of the driver, or the venv does not exist.
Run the Setup block, or drop --bin to use the python3 -m opossum fallback.no README.md was written — did 'opossum init' run?: the driver could
not execute the binary at all. Check --bin points at something runnable;
with no --bin, confirm python3 -c "import opossum" works from the repo.error: no README.md found, pass one with --path: you ran a command
outside any list directory and above any README.md. cd into the list.pip install -e . says "does not appear to be a Python project": you ran
it from the wrong directory. It needs the repo root, where pyproject.toml
is.