Script Quality Criteria

Scripts provide deterministic reliability and token efficiency.

When to Include Scripts

Same code rewritten repeatedly
Deterministic operations needed
Complex transformations
External tool integrations

Cross-Platform Requirements

Prefer: Node.js or Python Avoid: Bash scripts (not well-supported on Windows)

If bash required, provide Node.js/Python alternative.

Testing Requirements

Mandatory: All scripts must have tests

# Run tests before packaging
python -m pytest scripts/tests/
# or
npm test

Tests must pass. No skipping failed tests.

Environment Variables

Respect hierarchy (first found wins):

process.env (runtime)
$HOME/.opencode/skills/<skill-name>/.env (skill-specific)
$HOME/.opencode/skills/.env (shared skills)
$HOME/.opencode/.env (global)
./.opencode/skills/${SKILL}/.env (cwd)
./.opencode/skills/.env (cwd)
./.opencode/.env (cwd)

Implementation pattern (Python):

from dotenv import load_dotenv
import os

# Load in reverse order (last loaded wins if not set)
load_dotenv('$HOME/.opencode/.env')
load_dotenv('$HOME/.opencode/skills/.env')
load_dotenv('$HOME/.opencode/skills/my-skill/.env')
load_dotenv('./.opencode/skills/my-skill/.env')
load_dotenv('./.opencode/skills/.env')
load_dotenv('./.opencode/.env')
# process.env already takes precedence

Documentation Requirements

.env.example

Show required variables without values:

API_KEY=
DATABASE_URL=
DEBUG=false

requirements.txt (Python)

Pin major versions:

requests>=2.28.0
python-dotenv>=1.0.0

package.json (Node.js)

Include scripts:

{
  "scripts": {
    "test": "jest"
  }
}

Manual Testing

Before packaging, test with real use cases:

# Example: PDF rotation script
python scripts/rotate_pdf.py input.pdf 90 output.pdf

Verify output matches expectations.

Error Handling

Clear error messages
Graceful failures
No silent errors
Exit codes: 0 success, non-zero failure

2.0 KiB Raw Blame History