init

.opencode/skills/skill-creator/references/script-quality-criteria.md

@@ -0,0 +1,106 @@
+# 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
+
+```bash
+# 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):
+
+1. `process.env` (runtime)
+2. `$HOME/.opencode/skills/<skill-name>/.env` (skill-specific)
+3. `$HOME/.opencode/skills/.env` (shared skills)
+4. `$HOME/.opencode/.env` (global)
+5. `./.opencode/skills/${SKILL}/.env` (cwd)
+6. `./.opencode/skills/.env` (cwd)
+7. `./.opencode/.env` (cwd)
+
+**Implementation pattern (Python):**
+
+```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:
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+## Manual Testing
+
+Before packaging, test with real use cases:
+
+```bash
+# 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