scripts-python

MCP gives Hermes tools. Skills give Hermes judgment. scripts-python gives Hermes a standard for the Python that runs your stack.

Current skill version: v1.0.0

Why this exists

Hermes already orchestrates terminal, files, profiles, cron, and secrets. What it still needs for serious tooling work is a rigid house style so every Python script looks the same, fails cleanly, and reads like a product - not vibecode.

scripts-python teaches Hermes (and you) to ship Python with:

Pillar	What you get
Locked skeleton	Banner header, argparse, run()/main() -> int, SystemExit
Stable conventions	snake_case, type hints, pathlib, f-strings, PascalCase classes
Authoring recipe	5-step path from intent to verified script
Craft bar	--dry-run, specific exceptions, no bare except, no secret dumps
Lean package	Skill law only - your host tools stay in your workspace

Complements Hermes. Does not replace it. Does not claim to be a general "learn Python" course.

Install (Hermes drop-in)

git clone https://github.com/Unix-Dev-Ops/scripts-python.git
mkdir -p ~/.hermes/skills/software-development
cp -a scripts-python/skills/software-development/scripts-python \
  ~/.hermes/skills/software-development/

In a Hermes session:

/reload-skills
/skill scripts-python

Load it automatically per profile via config.yaml:

skills:
  external_dirs:
    - /home/<you>/.hermes/skills/software-development/scripts-python

Standing rule (recommended in SOUL / AGENTS):

For long-lived Python scripts/tools: load skill scripts-python first.
Products go under profile workspace/scripts/ or ~/.hermes/scripts/<purpose>/.

Quickstart

Load scripts-python.
Copy templates/template_base.py to ~/.hermes/scripts/memory/prune_notes.py
Purpose: prune dated entries older than N days from a markdown file.
Args: --file PATH, --days N (default 14), --dry-run.
Stdlib only. Silent when run headless.

Then verify:

python3 -m py_compile ~/.hermes/scripts/memory/prune_notes.py
# ruff / mypy if available
python3 ~/.hermes/scripts/memory/prune_notes.py --help

Full walkthrough: skills/software-development/scripts-python/references/authoring.md

Package layout

skills/software-development/scripts-python/
  SKILL.md
  templates/template_base.py                    # ONLY executable skeleton
  references/python-conventions.md
  references/authoring.md
  README.md / PUBLISH.md

Not in this repo: private production tools, host design briefs, API keys, duplicate templates.

What "good" looks like

• Author / Date / Ver / Name / Define / Usage banner header (column-aligned)
• from __future__ import annotations; sorted imports; module constants in SCREAMING_SNAKE_CASE
• parse_args() -> run(args) -> int -> main() -> int -> raise SystemExit(main())
• Type hints everywhere; pathlib over os.path; f-strings only
• --dry-run for anything that mutates files; specific exception handling, never bare except
• Silent in headless/cron mode; structured output only for interactive CLIs

Contributing

PRs welcome. Maintainer review required.

• CONTRIBUTING.md - workflow, checklist, conventional commits
• MAINTAINERS.md - branch protection / merge style
• SECURITY.md - private vuln reports
• CODEOWNERS - @Unix-Dev-Ops

python3 -m py_compile skills/software-development/scripts-python/templates/template_base.py

Related

Project	Role
scripts-bash	Sibling skill: the bash standard
Hermes Agent	The agent this skill serves
Hermes docs	Official documentation

Author

Vituvo (@Unix-Dev-Ops)

Built for real Hermes operators who manage automation, local inference, and agent infrastructure with Python that does not apologize.

License

MIT - Copyright (c) 2026 Vituvo