Implementation as Glue: Where Python Runs

+15 Mana ✨
Environment Variable Passthrough(DOCUMENTATION)

Introduction

Skills are instructions, not code. But many real workflows have moments where running a small script is the cleanest path: parse some logs, render a template, verify an environment. The Skills format gives you scripts/ for that. The important thing is the framing: scripts are glue the agent reaches for, not background daemons. They run inside the same sandboxes (execute_code, terminal) the agent uses for everything else.

Key Concepts

  • scripts/: A conventional subdirectory for executable helpers.
  • templates/: A conventional subdirectory for output formats (Jinja, plain text, configuration shells).
  • references/: A conventional subdirectory for long-form documentation, loaded on demand.
  • assets/: A conventional subdirectory for supplementary files (images, fixtures, sample data).
  • Environment passthrough: Hermes forwards declared environment variables (via required_environment_variables) to script sandboxes automatically.

Real World Context

A terraform-plan-review skill instructs the agent to run a small Python script (scripts/summarize_plan.py) that takes the output of terraform plan and produces a structured summary. The script is 80 lines of plain Python. The agent invokes it via the execute_code tool. The summary becomes part of the conversation, and the agent uses it to write the review. The skill is the recipe; the script is the chopping board.

Deep Dive

The subdirectories under a skill each have a typical role:

scripts/. Small helpers the agent runs to do data crunching or environment checks. The SKILL.md body usually points the agent at them explicitly:

markdown
## Procedure
1. Run `scripts/preflight.py` via the `execute_code` tool. If exit code is non-zero, surface the error and stop.
2. ...

Scripts use the agent's existing sandboxes. There is no special privilege. If a script wants the terminal, it runs through the terminal tool; if it wants Python, through execute_code. The sandboxes' policies still apply.

templates/. Output formats the agent fills in. Jinja templates are common, but plain text with placeholders works too. (This subdirectory is a Hermes-recognized convention. The minimal agentskills.io spec lists only scripts/, references/, and assets/; templates can equivalently live under assets/.) The body typically says something like:

markdown
## Procedure
3. Render `templates/pr_body.md.j2` with the values you collected. Show the result to the user.

The agent can use the read_file and write_file tools to load and emit templates without needing a custom helper.

references/. Longer documents the agent does not need every time. A ## References section in the body can call them out:

markdown
## References
- `references/edge-cases.md` for the full list of Postgres lock modes
- `references/migration-history.md` for a chronological log of prior migrations

Level 2 of progressive disclosure is exactly this: the agent picks one reference to load, not all of them. References give you room to be thorough without bloating the active context.

assets/. Anything else. Sample CSVs, fixture images, baseline screenshots. Useful for skills that produce visual outputs or that compare against a known good state.

Environment variables that scripts need should be declared at the top of SKILL.md:

yaml
required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

When the skill loads, Hermes ensures the variable is present (asking the user securely if not), then forwards it to the script sandboxes. The script accesses it as a normal environment variable. No bespoke wiring.

Common Pitfalls

  1. Putting credentials inside the skill files: Never. Use required_environment_variables and let Hermes pass them through. Bundled credentials end up in version control and search indexes.
  2. Writing scripts that do not surface errors clearly: The agent sees stdout and exit codes. A script that swallows errors and exits 0 will leave the agent confused. Fail loudly.

Best Practices

  1. Keep scripts small and single-purpose: One script per logical step. The SKILL.md orchestrates the steps; the script does one thing.
  2. Document scripts in the SKILL.md body: Do not rely on the agent inferring what scripts/foo.py does from the filename. Say it in the body.

Summary

  • scripts/ holds executable glue the agent runs via existing sandboxes.
  • templates/ holds output formats the agent fills in.
  • references/ holds long-form documentation, loaded on demand at Level 2.
  • assets/ holds supplementary files.
  • Environment variables declared in required_environment_variables pass through to script sandboxes automatically.

Code Examples

python
# ~/.hermes/skills/devops/terraform-plan-review/scripts/summarize_plan.py
# A small helper the agent runs via execute_code.
import json
import sys

def main() -> int:
    plan = json.load(sys.stdin)
    changes = plan.get('resource_changes', [])
    additions = [c for c in changes if 'create' in c.get('change', {}).get('actions', [])]
    deletions = [c for c in changes if 'delete' in c.get('change', {}).get('actions', [])]
    print(f'additions={len(additions)} deletions={len(deletions)}')
    if deletions:
        print('DELETIONS:')
        for d in deletions:
            print(f"  - {d['address']}")
    return 0

if __name__ == '__main__':
    sys.exit(main())
✓ Completed