small-skill 0.0.1 → 0.0.3

package/README.md

@@ -1,18 +1,23 @@
 # small-skill
 
-The agent skill for [small-deploy](https://github.com/Pipeship-Studio/small-deploy):
+The agent skill for [small-deploy](https://github.com/yudhisteer/small-deploy):
 teaches Claude Code / Codex to deploy the Python tool it just built behind a
 work-email login in one command — and, when the tool needs AWS, to create and
 maintain the IAM role itself with least privilege.
 
 ## Install
 
+Two packages: the [small-deploy](https://www.npmjs.com/package/small-deploy)
+CLI does the deploying; this skill teaches your agent to drive it.
+
 ```
-npx small-skill            # into this project's .claude/skills/small
-npx small-skill --global   # into ~/.claude/skills/small for every project
+npm i -g small-deploy      # the CLI (the agent runs `small ...` through it)
+npx small-skill            # the skill, into this project's .claude/skills/small
+npx small-skill --global   # or into ~/.claude/skills/small for every project
 ```
 
-Or, with the CLI already installed: `small skill`.
+Or, with the CLI already installed: `small skill` installs the skill copy it
+ships with.
 
 ## What the agent learns
 

package/SKILL.md

@@ -51,6 +51,11 @@ debugging around it.
    Dockerfile, do not suggest hosting options, do not add auth — small already
    put the app behind a work-email login.
 
+7. Write AGENT.md (created empty by `small init`, uploaded with every deploy):
+   things the dashboard's Ask agent should know that the code doesn't say —
+   what the app is for, gotchas, who to contact. Two paragraphs, plain
+   English. You built the tool, so you write it.
+
 To give someone access when visibility is private, or edit rights:
 
 ```
@@ -58,6 +63,41 @@ small share alice@company.com          # view
 small share bob@company.com --edit     # can redeploy
 ```
 
+## The code already exists (a script that works locally or on Lambda)
+
+Do not rewrite it and do not require it to know about small. Keep the working
+file untouched and add a thin adapter as the entry:
+
+```python
+# job.py — adapter. Each [inputs] field in small.toml arrives as an env var:
+# source -> SMALL_INPUT_SOURCE. Files written to $SMALL_OUTPUTS become run outputs.
+import os
+from mytool import main                     # the user's file, unchanged
+
+result = main(
+    source=os.environ["SMALL_INPUT_SOURCE"],
+    limit=int(os.environ.get("SMALL_INPUT_LIMIT", "10")),
+)
+result.save(os.path.join(os.environ["SMALL_OUTPUTS"], "result.csv"))
+```
+
+For a Lambda handler, the adapter builds the `event` dict from the
+`SMALL_INPUT_*` vars and calls `handler(event, None)`.
+
+The entry file name is free — `entry` in `small.toml` points at whatever you
+wrote (adapter or the original file if the user is fine editing it). Leave the
+two contract comments in the adapter: they are how the next human learns the
+wiring without reading platform source.
+
+## The run contract, in one breath
+
+`[inputs]` in `small.toml` defines the fields once. Every trigger — the
+dashboard Run form, `small run`, `/small run` in Slack, the chat agent's Run
+button, a cron schedule, Run again — delivers the values the same way:
+`SMALL_INPUT_<NAME>` env vars (files land under `$SMALL_INPUTS`). Every file
+the script writes to `$SMALL_OUTPUTS` becomes a run output on the dashboard,
+regardless of trigger. The script never knows who started it.
+
 If `small` is not installed: `npm i -g small-deploy`. If not logged in the
 deploy fails with "run small login" — have the user run `small login`
 interactively (it emails them a 6-digit code).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "small-skill",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Agent skill for small-deploy: teaches Claude Code/Codex to deploy a Python tool behind a work-email login in one command",
   "bin": {
     "small-skill": "bin/install.js"

package/references/jobs.md

@@ -1,50 +1,62 @@
-# Jobs — inputs and outputs
-
-Read this when the tool is a script that runs on demand (`kind = "job"`).
-
-Every non-secret `os.environ` read in a job is an input — declare it in
-`small.toml` instead of leaving it an undeclared env var:
-
-```toml
-[inputs]
-image     = { type = "file",   required = true, accept = ".jpg,.png", help = "Photo to analyse" }
-threshold = { type = "number", default = 0.5, min = 0, max = 1 }
-
-[outputs]
-annotated = { path = "annotated.jpg", label = "Annotated image" }
-```
-
-Six types: `file`, `number`, `select`, `date`, `text`, `bool`. Callers pass
-them as flags — `small run app --image ./photo.jpg --threshold 0.7` — and the
-dashboard renders a Run form from the same declaration. In the script:
-
-- scalars arrive as `SMALL_INPUT_<NAME>` env vars (uppercase; bools are the
-  strings `true`/`false`)
-- file paths come from `$SMALL_INPUTS/inputs.json` (each file value is the
-  path it was fetched to)
-
-Anything the script saves for the user goes in `$SMALL_OUTPUTS` — every file
-written there is captured on the run, shown in the dashboard, and fetched with
-`small run app --download ./out`. Do not print results to stdout when a file
-would serve better, and do not write user-facing files anywhere else in the
-container: only `$SMALL_OUTPUTS` survives the machine.
-
-## Schedules
-
-A job that should run itself carries a standard 5-field cron expression, UTC:
-
-```toml
-kind = "job"
-schedule = "0 9 * * 1-5"
-```
-
-Deploy validates it (bad or never-firing expressions stop with a one-line
-fix) and prints the next run. `small schedule pause app` /
-`small schedule resume app` flip it without losing the expression; `small
-runs` shows cron runs with a `⏱ cron` marker. Scheduled runs pass **no
-inputs at all** (not even defaults — those are applied by the CLI): a
-scheduled job's script must fall back in code,
-`os.environ.get("SMALL_INPUT_THRESHOLD", "0.5")`, or not be scheduled.
-
-S3 in/out: declare the URI and destination bucket as `text` inputs and use
-boto3 in the script — see references/aws-role.md for the role.
+# Jobs — inputs and outputs
+
+Read this when the tool is a script that runs on demand (`kind = "job"`).
+
+Every non-secret `os.environ` read in a job is an input — declare it in
+`small.toml` instead of leaving it an undeclared env var:
+
+```toml
+[inputs]
+image     = { type = "file",   required = true, accept = ".jpg,.png", help = "Photo to analyse" }
+threshold = { type = "number", default = 0.5, min = 0, max = 1 }
+
+[outputs]
+annotated = { path = "annotated.jpg", label = "Annotated image" }
+```
+
+Six types: `file`, `number`, `select`, `date`, `text`, `bool`. Callers pass
+them as flags — `small run app --image ./photo.jpg --threshold 0.7` — and the
+dashboard renders a Run form from the same declaration. Slack (`/small run`),
+the chat agent's Run proposals, cron, and Run again all feed the same
+declaration too: the script receives identical env vars no matter who or what
+started the run. In the script:
+
+- scalars arrive as `SMALL_INPUT_<NAME>` env vars (uppercase; bools are the
+  strings `true`/`false`)
+- file paths come from `$SMALL_INPUTS/inputs.json` (each file value is the
+  path it was fetched to)
+
+Anything the script saves for the user goes in `$SMALL_OUTPUTS` — every file
+written there is captured on the run, shown in the dashboard, and fetched with
+`small run app --download ./out`. Do not print results to stdout when a file
+would serve better, and do not write user-facing files anywhere else in the
+container: only `$SMALL_OUTPUTS` survives the machine.
+
+## Schedules
+
+A job that should run itself carries a standard 5-field cron expression, UTC:
+
+```toml
+kind = "job"
+schedule = "0 9 * * 1-5"
+```
+
+Deploy validates it (bad or never-firing expressions stop with a one-line
+fix) and prints the next run. `small schedule pause app` /
+`small schedule resume app` flip it without losing the expression; `small
+runs` shows cron runs with a `⏱ cron` marker. Scheduled runs pass **no
+inputs at all** (not even defaults — those are applied by the CLI): a
+scheduled job's script must fall back in code,
+`os.environ.get("SMALL_INPUT_THRESHOLD", "0.5")`, or not be scheduled.
+
+S3 in/out: declare the URI and destination bucket as `text` inputs and use
+boto3 in the script — see references/aws-role.md for the role.
+
+## Existing scripts
+
+When the working code predates small (local script, Lambda handler), keep it
+untouched and write a thin adapter as the entry — SKILL.md, "The code already
+exists". The adapter is the only file that reads `SMALL_INPUT_*` or writes to
+`$SMALL_OUTPUTS`; the original stays runnable everywhere it already runs.
+Always leave the two contract comments in the adapter so the next reader
+learns the env-var mapping from the code itself.