Skip to content

README.md

Latest commit

 

History

History
167 lines (128 loc) · 5.26 KB

README.md

File metadata and controls

167 lines (128 loc) · 5.26 KB
Raw

Python Project Workflow

License: MIT CI Python 3.10+ agentskills.io

Portable Python project workflow skill for agentskills.io-compatible agents.

This repo ships an adaptive skill that handles greenfield bootstrap, tooling configuration, CI setup, packaging, mature-repo preservation, and cross-platform verification. No agent-specific commands or paths — compatible with Hermes, Claude Code, Codex CLI, Gemini CLI, OpenCode, and any agentskills.io client.

  • Greenfield projects — scaffold pyproject.toml (PEP 621), src/ layout, uv, Ruff, mypy, pytest, and Google-style docstrings
  • Existing projects — discover the project's own tooling, work within its conventions. No forced migration.
  • Mature repositories — preservation-first workflow; find the native gate, respect conventions, avoid broad defaults, and report before editing
  • CI/verification — project-native gates, cross-platform tool patterns, ad-hoc verification when no gate exists
  • Packaging — build, publish, entry points, lockfile policy

It is not a Python code-review rule set. For code-review findings, use a dedicated review skill such as py-review-skill.

Quick Start

Make the skill discoverable by your agent.

Hermes Agent 
hermes skills install CodeSigils/python-project-workflow-skill
# Or add to external_dirs in ~/.hermes/config.yaml:
# skills:
#   external_dirs:
#     - /path/to/python-project-workflow/skills
Claude Code 
cp -r skills/python-project-workflow ~/.claude/skills/
Codex CLI 
cp -r skills/python-project-workflow ~/.codex/skills/
Gemini CLI / .agents/ path 
cp -r skills/python-project-workflow .agents/skills/
OpenCode 
cp -r skills/python-project-workflow .opencode/skills/

For agents that support external skill directories, point the config at skills/python-project-workflow/ for live-updating access.

How to Use

  1. Load python-project-workflow when working with a Python project.
  2. The skill classifies your project — greenfield, existing, mature, or automation — and loads the relevant reference file automatically.
  3. Review the orientation checklist (in SKILL.md § Orientation Checklist) to understand the project's Python version contract, tooling, and layout before editing.
  4. Use the task classification table in SKILL.md to load the right reference for your task.

All references are self-contained. No external setup, config files, or environment variables required.

Portability

Each shipped file in skills/ is checked by CI for agent-specific references (skill_view, hermes skills, from hermes_tools, platform adapter paths, etc.). If a commit adds a platform-specific command, CI fails before it reaches the runtime.

The current surface is entirely cross-agent compatible — zero platform references in any shipped skill file or reference.

Verify

python3 .github/scripts/check-portability.py
python3 scripts/validate.py
python3 scripts/verify-urls.py
python3 -m ruff check scripts

Layout

python-project-workflow/
├── LICENSE
├── CITATION.cff
├── SECURITY.md
├── README.md
├── .gitignore
├── .gitattributes
├── .github/
│   ├── workflows/ci.yml
│   └── scripts/check-portability.py
├── scripts/
│   ├── validate.py
│   └── verify-urls.py
└── skills/
    └── python-project-workflow/
        ├── SKILL.md                         # orientation inlined
        └── references/
            ├── pyproject-template.md
            ├── lint-format-typing-testing.md
            ├── core-footguns.md
            ├── safe-editing.md
            ├── mature-repo-preservation.md
            └── eval-benchmark-hardening.md

Shipping boundary: skills/python-project-workflow/ is the runtime payload and source of truth. Everything else is repository-only development infrastructure.

References

Reference Purpose
pyproject-template.md Modern baseline template with PEP 621 metadata
lint-format-typing-testing.md Practical uv/Ruff/mypy/pytest commands and cross-platform tool guidance
core-footguns.md Common Python pitfalls with examples and patterns
safe-editing.md Safe edit workflow for backslash-heavy content
mature-repo-preservation.md Preservation-first workflow for established repos
eval-benchmark-hardening.md Benchmark and eval hardening guidance

The Orientation Checklist is now inlined in SKILL.md § Orientation Checklist.

License

MIT — see LICENSE.