Skip to content

code-yeongyu/oh-my-openagent / packages/shared-skills/skills/programming

programming

Unverified

Applies strict, modern language practice (typed errors, exhaustive match, tests that can fail) for Python, Rust, TypeScript, JavaScript, and Go. Use for work on .py, .rs, .ts, .js, or .go files, and whenever a test or spec file is written, reshaped, reviewed, or deleted: the four-question test authoring gate and the junk-test classes live here.

FileKindSize
SKILL.mdskill md33.3 KB
references/code-smells.mdmarkdown13.9 KB
references/go/README.mdmarkdown7.7 KB
references/go/backend-stack.mdmarkdown16.6 KB
references/go/bootstrap.mdmarkdown8.9 KB
references/go/bubbletea-v2.mdmarkdown11.3 KB
references/go/cobra-stack.mdmarkdown11.5 KB
references/go/concurrency.mdmarkdown10.9 KB
references/go/data-modeling.mdmarkdown12.0 KB
references/go/error-handling.mdmarkdown10.1 KB
references/go/golangci-strict.mdmarkdown10.0 KB
references/go/grpc-connect.mdmarkdown10.3 KB
references/go/libraries.mdmarkdown13.7 KB
references/go/one-liners.mdmarkdown5.5 KB
references/go/sqlc-pgx.mdmarkdown12.7 KB
references/go/testing.mdmarkdown14.2 KB
references/go/type-patterns.mdmarkdown9.5 KB
references/logging.mdmarkdown10.5 KB
references/python/README.mdmarkdown15.7 KB
references/python/async-anyio.mdmarkdown14.2 KB
references/python/data-modeling.mdmarkdown6.6 KB
references/python/data-processing.mdmarkdown4.2 KB
references/python/error-handling.mdmarkdown6.0 KB
references/python/fastapi-stack.mdmarkdown9.2 KB
references/python/httpx2-optimization.mdmarkdown12.0 KB
references/python/libraries.mdmarkdown10.6 KB
references/python/one-liners.mdmarkdown7.9 KB
references/python/orjson-stack.mdmarkdown13.3 KB
references/python/pydantic-ai.mdmarkdown8.2 KB
references/python/pyproject-strict.mdmarkdown9.0 KB
references/python/textual-tui.mdmarkdown5.1 KB
references/python/type-patterns.mdmarkdown4.1 KB
references/rust-ub/README.mdmarkdown9.9 KB
references/rust-ub/miri-sanitizers-loom.mdmarkdown11.5 KB
references/rust-ub/ub-taxonomy.mdmarkdown13.3 KB
references/rust/README.mdmarkdown16.6 KB
references/rust/api-design.mdmarkdown6.5 KB
references/rust/async-tokio.mdmarkdown12.6 KB
references/rust/axum-stack.mdmarkdown14.2 KB
references/rust/cargo-strict.mdmarkdown10.0 KB
references/rust/clap-stack.mdmarkdown12.1 KB
references/rust/concurrency.mdmarkdown14.3 KB
references/rust/libraries.mdmarkdown17.4 KB
references/rust/macros.mdmarkdown3.3 KB
references/rust/one-liners.mdmarkdown7.5 KB
references/rust/proptest-insta.mdmarkdown13.9 KB
references/rust/type-state.mdmarkdown13.1 KB
references/rust/unsafe-discipline.mdmarkdown12.9 KB
references/rust/zero-cost-safety.mdmarkdown16.9 KB
references/testing/README.mdmarkdown10.3 KB
references/testing/junk-classes.mdmarkdown6.2 KB
references/typescript/README.mdmarkdown10.6 KB
references/typescript/backend-hono.mdmarkdown21.2 KB
references/typescript/bootstrap.mdmarkdown6.9 KB
references/typescript/data-modeling.mdmarkdown5.0 KB
references/typescript/error-handling.mdmarkdown4.7 KB
references/typescript/oxc-lint.mdmarkdown7.6 KB
references/typescript/tsconfig-strict.mdmarkdown3.9 KB
references/typescript/type-patterns.mdmarkdown5.2 KB
scripts/go/check-no-excuse-rules.shexecutablescript7.1 KB
scripts/go/new-project.tsscript6.8 KB
scripts/go/templates/.editorconfigother206 B
scripts/go/templates/.golangci.ymlconfig1.5 KB
scripts/go/templates/AGENTS.md.tmplother845 B
scripts/go/templates/README.md.tmplother207 B
scripts/go/templates/Taskfile.ymlconfig706 B
scripts/go/templates/ci.ymlconfig863 B
scripts/go/templates/config.goscript643 B
scripts/go/templates/gitignoreother99 B
scripts/go/templates/main.go.tmplother329 B
scripts/go/templates/run.goscript350 B
scripts/python/check-no-excuse-rules.pyscript24.9 KB
scripts/python/new-project.tsscript6.7 KB
scripts/python/new-script.tsscript4.2 KB
scripts/rust/check-no-excuse-rules.shexecutablescript7.5 KB
scripts/rust/check-no-excuse-rules.test.tsscript3.4 KB
scripts/rust/new-project.tsscript6.1 KB
scripts/scaffolders.test.tsscript4.9 KB
scripts/shared/run-tool.tsscript855 B
scripts/typescript/check-no-excuse-rules.test.tsscript4.0 KB
scripts/typescript/check-no-excuse-rules.tsscript13.1 KB
scripts/typescript/check-test-junk-rules.tsscript5.5 KB
scripts/typescript/check-test-junk.test.tsscript4.9 KB
scripts/typescript/check-test-junk.tsscript5.4 KB
scripts/typescript/mutation-proof.test.tsscript1.9 KB
scripts/typescript/mutation-proof.tsscript6.4 KB
scripts/typescript/new-project.test.tsscript6.8 KB
scripts/typescript/new-project.tsscript3.1 KB
scripts/typescript/oxc/.oxfmtrc.jsonconfig256 B
scripts/typescript/oxc/.oxlintrc.jsonconfig1.7 KB
scripts/typescript/oxc/lint/oxlint-plugin/LICENSEother1.0 KB
scripts/typescript/oxc/lint/oxlint-plugin/index.jsscript288 B
scripts/typescript/oxc/lint/oxlint-plugin/no-em-dash-copy.jsscript785 B
scripts/typescript/oxc/lint/oxlint-plugin/require-suppression-reason.jsscript2.3 KB
scripts/typescript/oxc/tsconfig.jsonconfig794 B

references/python/one-liners.md

View on GitHub
# One-liner Scripts (PEP 723 + uv)

Self-contained Python scripts with declared dependencies, run with no environment setup. The combination eliminates the historical reason to write small tools in Go or Bash.

**Rule: EVERY `.py` script — even throwaway — MUST use PEP 723 inline metadata with the usage comment block.** No venv, no requirements.txt, no setup.py. The script IS the environment spec.

## The two patterns

### Pattern 1: inline `uv run` invocation

```bash
uv run --with httpx2 --with rich python -c "
import httpx2
from rich import print
print(httpx2.get('https://api.github.com').json())
"
```

Use for terminal one-shots that you don't want to save. `--with PKG` may be repeated.

### Pattern 2: PEP 723 script with shebang (THE CANONICAL PATTERN)

A regular `.py` file with metadata in a comment block. uv reads the metadata, materialises a disposable venv (cached), and runs the script.

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "httpx2[http2,brotli,zstd]",
#     "rich",
# ]
# ///

# ─── How to run ───
# 1. Install uv (if not installed):
#      curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Run directly (no venv, no pip install needed):
#      uv run my_script.py
# 3. Or make executable and run:
#      chmod +x my_script.py && ./my_script.py
# ──────────────────

from __future__ import annotations

import httpx2
from rich import print as rprint


def main() -> None:
    with httpx2.Client(http2=True, follow_redirects=True) as client:
        resp = client.get("https://api.github.com")
        resp.raise_for_status()
        rprint(resp.json())


if __name__ == "__main__":
    main()
```

### Mandatory elements

Every PEP 723 script MUST include these, in order:

1. **Shebang**: `#!/usr/bin/env -S uv run --script`
2. **PEP 723 metadata block**: `# /// script` ... `# ///` with `requires-python` and `dependencies`
3. **Usage comment block**: How to install uv + how to run the script. Copy the template above verbatim.
4. **`from __future__ import annotations`**: Always first import.
5. **`if __name__ == "__main__": main()`**: Entry point guard.

### The usage comment block (NON-NEGOTIABLE)

```python
# ─── How to run ───
# 1. Install uv (if not installed):
#      curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Run directly (no venv, no pip install needed):
#      uv run <SCRIPT_NAME>.py [ARGS]
# 3. Or make executable and run:
#      chmod +x <SCRIPT_NAME>.py && ./<SCRIPT_NAME>.py
# ──────────────────
```

Replace `<SCRIPT_NAME>` with the actual filename. Add argument descriptions if the script takes CLI args. This block goes immediately after the `# ///` closing line, before any imports.

**Why mandatory**: Anyone who receives this script — colleague, CI, future you — must know how to run it without reading docs. The comment IS the docs.

## Template generator

Use `../../scripts/python/new-script.ts` (Bun) to scaffold a new PEP 723 script with all boilerplate pre-filled:

```bash
# Generate to temp directory (default)
bun run ../../scripts/python/new-script.ts my_tool

# Generate to specific path
bun run ../../scripts/python/new-script.ts my_tool --output ./scripts/my_tool.py

# With extra dependencies (repeat --deps for each)
bun run ../../scripts/python/new-script.ts my_tool --deps polars --deps duckdb --deps rich
```

## Common dependency sets

| Use case | Dependencies line |
|---|---|
| API client | `"httpx2[http2,brotli,zstd]"` |
| Data processing | `"polars"`, `"duckdb"` |
| CLI tool | `"typer"`, `"rich"` |
| Web scraping | `"httpx2[http2,brotli,zstd]"`, `"selectolax"` |
| File watcher | `"watchfiles"` |
| JSON pretty | `"rich"` |
| AI / LLM | `"pydantic-ai"`, `"httpx2[http2,brotli,zstd]"` |

## Real-world examples

### Fetch + print JSON

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "httpx2[http2,brotli,zstd]",
#     "rich",
# ]
# ///

# ─── How to run ───
# 1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Run: uv run fetch_json.py https://api.github.com/repos/pydantic/httpx2
# ──────────────────

from __future__ import annotations

import sys

import httpx2
from rich import print as rprint


def main() -> None:
    url = sys.argv[1] if len(sys.argv) > 1 else "https://api.github.com"
    with httpx2.Client(http2=True, follow_redirects=True) as client:
        resp = client.get(url)
        resp.raise_for_status()
        rprint(resp.json())


if __name__ == "__main__":
    main()
```

### CSV → Parquet conversion

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "polars",
#     "typer",
#     "rich",
# ]
# ///

# ─── How to run ───
# 1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Run: uv run csv2parquet.py input.csv output.parquet
# ──────────────────

from __future__ import annotations

from pathlib import Path

import polars as pl
import typer
from rich import print as rprint


def main(input_path: Path, output_path: Path | None = None) -> None:
    """Convert CSV to Parquet."""
    out = output_path or input_path.with_suffix(".parquet")
    df = pl.read_csv(input_path)
    df.write_parquet(out)
    rprint(f"[green]✓[/green] {input_path} → {out} ({len(df)} rows)")


if __name__ == "__main__":
    typer.run(main)
```

### Quick benchmark

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "httpx2[http2,brotli,zstd]",
#     "rich",
#     "anyio",
# ]
# ///

# ─── How to run ───
# 1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Run: uv run bench.py https://api.example.com/health 50
# ──────────────────

from __future__ import annotations

import socket
import sys
import time

import anyio
import httpx2
from rich import print as rprint


async def main() -> None:
    url = sys.argv[1] if len(sys.argv) > 1 else "https://api.github.com"
    n = int(sys.argv[2]) if len(sys.argv) > 2 else 20

    limits = httpx2.Limits(max_connections=200, max_keepalive_connections=40, keepalive_expiry=30.0)
    timeout = httpx2.Timeout(connect=5.0, read=30.0, write=10.0, pool=10.0)
    transport = httpx2.AsyncHTTPTransport(
        http2=True, retries=3, limits=limits,
        socket_options=[(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)],
    )

    async with httpx2.AsyncClient(transport=transport, timeout=timeout, follow_redirects=True) as client:
        # warmup
        for _ in range(3):
            await client.get(url)

        start = time.perf_counter()
        for _ in range(n):
            r = await client.get(url)
            assert r.status_code == 200
        elapsed = time.perf_counter() - start

    avg_ms = (elapsed / n) * 1000
    rprint(f"[bold]{url}[/bold]: {avg_ms:.1f}ms avg over {n} requests ({elapsed:.2f}s total, {r.http_version})")


if __name__ == "__main__":
    anyio.run(main)
```

## Anti-patterns

| ❌ Don't | ✅ Do |
|---|---|
| `pip install httpx2 && python script.py` | `uv run script.py` |
| `requirements.txt` alongside script | PEP 723 inline metadata |
| `python -m venv .venv && ...` | `uv run --script` handles it |
| Script without usage comment | Always include the "How to run" block |
| `import asyncio; asyncio.run(main())` | `import anyio; anyio.run(main)` |
| Bare `httpx2.AsyncClient()` | Full production defaults (see `references/python/httpx2-optimization.md`) |

## Sources

- PEP 723 - Inline script metadata: <https://peps.python.org/pep-0723/>
- uv `run --script` docs: <https://docs.astral.sh/uv/guides/scripts/>
- Original article: <https://www.cottongeeks.com/articles/2025-06-24-fun-with-uv-and-pep-723>
- Simon Willison on one-shot Python tools: <https://simonwillison.net/2024/Dec/19/one-shot-python-tools/>
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall