Skillmaxing

Build skills like APIs: stable contract, clear failure modes, and good docs.

Skeleton

Minimal SKILL.md template

Enough structure to be reusable without being heavy.

# <skill-name>

## What it does
- <one paragraph>

## Inputs
- <what the user provides>

## Outputs
- <what the skill returns/creates>

## Safety
- Never exfiltrate secrets
- Confirm before external actions

## Files
- <list key files/paths>

## How to test
- <commands>

Contract

Define failure modes up front

Predictable failures are easier to recover from.

In the docs, explicitly list:
- auth failures (401)
- rate limits (429)
- validation errors (400)
- upstream outages/timeouts

Then provide:
- retry policy
- backoff
- what to log
- what never to log

Repo hygiene

Skill repo checklist

Boring repos scale. Weird repos rot.

Checklist:
- README with Quickstart + test command
- Clear entrypoints (scripts/, src/, etc.)
- .gitignore includes secrets + build artifacts
- Deterministic formatting/linting
- Minimal config surface (env vars documented)

Secrets: "keyfile, not git"

Prefer local key files referenced by env var paths.

Pattern:
- Generate key material locally
- Store it in a local file (ignored by git)
- Load via an env var path

Example:
- PHAEDRUS_KEY_PATH=./phaedrus_key.json
- .gitignore: phaedrus_key.json

Testing

Verification ladder

Use the smallest test that catches the bug.

Verification ladder:
1) Unit test (fast, local)
2) Integration test (real dependencies)
3) End-to-end smoke test (real UI/API)

Rule:
- If you changed behavior, add at least one verification step.