Merge pull request #55 from james-see/feat/agent-template

Add agent support files and repository guidance

Author: james-see

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.opencode/skills/python-examples/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: python-examples
+description: Navigate and safely extend the james-see/python-examples repository. Use when a user asks about learning Python libraries, running example scripts, adding a new example, cleaning an example, or adapting one of these scripts.
+---
+
+# Python Examples
+
+This repository contains standalone examples for common Python libraries. It is not
+a library package; run individual scripts directly.
+
+## Workflow
+
+1. Inspect the target example script before making changes.
+2. Check it compiles with `python -m py_compile python-examples/<file>`.
+3. Do not run network/API examples unless the user explicitly requests it.
+4. Follow `.env.example` for secrets.
+5. Add concise, focused examples rather than large multi-concept scripts.
+6. Keep dependencies in `pyproject.toml` and `uv.lock` when adding imports.
+
+## Safety
+
+- Never commit API keys, tokens, or personal data.
+- Use read-only or throwaway accounts for paid/remote APIs.
+- Place scripts that produce large side effects under `python-examples/` with clear warnings.
+
+## Suggested quality checks
+
+```sh
+uv run ruff check --fix python-examples
+uv run python -m py_compile python-examples/example.py
+```

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

AGENTS.md

@@ -0,0 +1,56 @@
+# Agent Guide for `python-examples`
+
+This repository is a collection of small, focused Python examples. It is not a
+published Python package; individual files are meant to be copied or adapted.
+
+## Navigation
+
+- Examples are in `python-examples/`.
+- File names use `-example.py`.
+- Shared boilerplate may live in `python-examples/main.py`, `useragents.py`, or `src/` inside the script.
+- Data and fixtures are usually next to the example that uses them.
+- Documentation for the Astro site lives in `docs/`.
+
+## Run examples
+
+```sh
+uv run python python-examples/requests-example.py
+```
+
+or activate the environment first:
+
+```sh
+uv sync
+source .venv/bin/activate
+python python-examples/requests-example.py
+```
+
+## Conventions
+
+- Target Python `>=3.12`.
+- Prefer the existing style and imports of the nearest example.
+- Keep examples small and one-concept focused.
+- Do not add network credentials. Use `.env.example`.
+- Prefer `pathlib.Path` for new filesystem code.
+- Add comments when an example demonstrates a non-obvious API behavior.
+- Make scripts safe to import, especially when rerun by agents.
+
+## Testing
+
+There is no central application test suite. Smoke-test a changed example with:
+
+```sh
+python -m py_compile python-examples/<name>-example.py
+```
+
+For dependency changes:
+
+```sh
+uv lock --check
+uv sync
+```
+
+## Security and cost
+
+Examples may hit third-party APIs. Do not run them automatically unless the user
+explicitly asks, and never commit API keys or tokens.

skills/python-examples/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: python-examples
+description: Navigate and safely extend the james-see/python-examples repository. Use when a user asks about learning Python libraries, running example scripts, adding a new example, cleaning an example, or adapting one of these scripts.
+---
+
+# Python Examples
+
+This repository contains standalone examples for common Python libraries. It is not
+a library package; run individual scripts directly.
+
+## Workflow
+
+1. Inspect the target example script before making changes.
+2. Check it compiles with `python -m py_compile python-examples/<file>`.
+3. Do not run network/API examples unless the user explicitly requests it.
+4. Follow `.env.example` for secrets.
+5. Add concise, focused examples rather than large multi-concept scripts.
+6. Keep dependencies in `pyproject.toml` and `uv.lock` when adding imports.
+
+## Safety
+
+- Never commit API keys, tokens, or personal data.
+- Use read-only or throwaway accounts for paid/remote APIs.
+- Place scripts that produce large side effects under `python-examples/` with clear warnings.
+
+## Suggested quality checks
+
+```sh
+uv run ruff check --fix python-examples
+uv run python -m py_compile python-examples/example.py
+```