{
  "markdown": "# Transloadit Skills\n\nThis repo hosts agent skills for Transloadit.\n\nIf you’re a developer/agent consuming this repo, start with the `transloadit` router skill and then jump into a specific `docs-*`, `transform-*`, or `integrate-*` skill.\n\n## Install / Use\n\nThis repo is compatible with the `skills` installer CLI (https://skills.sh/).\n\nBrowse what’s available:\n```bash\nnpx -y skills add https://github.com/transloadit/skills --list\n```\n\nInstall into this project (or use `-g` for user-level):\n```bash\nnpx -y skills add https://github.com/transloadit/skills --all\n```\n\nInstall a single skill (direct path):\n```bash\nnpx -y skills add https://github.com/transloadit/skills/tree/main/skills/docs-transloadit-robots\n```\n\nLocal dev (already cloned):\n```bash\nnpx -y skills add ./skills --list\nnpx -y skills add ./skills --all\n```\n\nManual option (symlink the `skills/` catalog into your agent’s skill directory):\n```bash\ngit clone https://github.com/transloadit/skills\nln -s /ABS/PATH/TO/THIS/REPO/skills ~/.codex/skills\nln -s /ABS/PATH/TO/THIS/REPO/skills ~/.claude/skills\nln -s /ABS/PATH/TO/THIS/REPO/skills ~/.gemini/skills\n```\n\nNote: this repo also contains developer-only skills under `.ai/dev-skills/` for working on this repo. The public catalog lives under `skills/`.\n\n## Skill Catalog\n\nCategories:\n- `docs-*`: offline reference lookups (no API calls)\n- `transform-*`: one-off transforms (CLI driven, outputs downloaded via `-o`)\n- `integrate-*`: real-world integration guides (validated via `scenarios/` + E2E, but not requiring any test harness)\n\nExamples:\n- `transform-generate-image-with-transloadit`\n- `transform-remove-background-with-transloadit`\n- `transform-describe-image-with-transloadit`\n- `transform-convert-markdown-to-pdf-with-transloadit`\n- `transform-transcribe-audio-with-transloadit`\n- `transform-build-polaroid-collage-with-transloadit`\n- `transform-build-mosaic-collage-with-transloadit`\n- `integrate-uppy-transloadit-s3-uploading-to-nextjs`\n\nThe public catalog is whatever currently lives under [`skills/`](/Users/kvz/code/skills/skills).\nFor a current list, use:\n\n```bash\nnpx -y skills add https://github.com/transloadit/skills --list\n```\n\nOr inspect the directories under `skills/` directly.\n\nBuiltin template discovery (token-efficient NDJSON, good for agents):\n```bash\nnpx -y @transloadit/node templates list --include-builtin exclusively-latest --fields id,name --json\n```\n\n## Conventions (For Agents)\n\n- Prefer `npx -y @transloadit/node ...` for any Transloadit-side operations and use `-j/--json` when parsing output.\n- For one-off `transform-*` skills, prefer an explicit input/output contract and a final output-file existence check.\n- The `@transloadit/node` CLI resolves auth in this order: shell env, the current working directory `.env`, then `~/.transloadit/credentials`.\n- The `.env` lookup is cwd-only. If a repo-root `.env` lives above the current directory, export the vars into the shell instead of relying on parent-directory discovery.\n- When documenting user-level CLI usage, present `~/.transloadit/credentials` as the default fallback and note that a cwd `.env` still takes precedence.\n- Never expose `TRANSLOADIT_SECRET` to the browser; keep signing strictly server-side.\n- `integrate-*` skills are written as real app integration playbooks (framework-agnostic where possible).\n- `scenarios/` are internal reference implementations with E2E validation; they are not required by the skills.\n\n## Notes\n\nRepository layout:\n- `skills/`: skill catalog (`skills/<name>/SKILL.md`)\n- `scenarios/`: runnable reference implementations (E2E-validated)\n- `scripts/`: internal harness tooling (not a skill)\n- `starter-projects/`: starter templates used by the harness (not a skill)\n\nSkill discovery is `SKILL.md`-based, so it’s fine for `starter-projects/` and `scenarios/` to be siblings of `skills/` without being interpreted as skills.\n\n## Contributing\n\n### Scenarios\n\n`scenarios/` is for integration scenarios that can later be distilled into agent skills.\n\nWorkflow (suggested):\n1. Create a scenario folder named after the intended skill.\n2. Research the current golden path (upstream docs, examples, and recent issues).\n3. Build a minimal, working project using latest dependencies.\n4. Prove it with an automated E2E test (real uploads, real processing).\n5. Condense into a `SKILL.md` with a narrow scope, clear inputs/outputs, and a runnable checklist.\n\nConventions:\n- Each scenario is self-contained (own `package.json`).\n- Secrets are read from env vars. Do not commit `.env*` files.\n- Prefer `npx -y @transloadit/node ...` for Transloadit-side operations (template creation, robot docs).\n\n### Add A Skill\n\n1. Create `skills/<skill-name>/SKILL.md` with tight scope and a runnable checklist.\n2. If it’s an integration, create a matching `scenarios/<skill-name>/` reference implementation and validate it with an E2E test.\n3. Keep test-harness specifics out of the skill. The skill should read like guidance for a normal production app.\n\n### Try-Skill Harness\n\nBefore committing, run:\n```bash\nyarn check\n```\n\n1. Provision a starter project under `starter-projects/<name>`.\n2. Each starter may include a `HARNESS.md` with starter-specific guidance for the agent-under-test.\n3. Verify the starter is in a clean, committed state (no `node_modules/`, build artifacts, or run output).\n4. Implement `scripts/try-skill.ts` with args `--skill <skill-name> --starter-project <name>`.\n5. `scripts/try-skill.ts` must copy the starter into an isolated run dir under `starter-projects/_runs/...` (excluding `node_modules`, `.next`, `dist`, `playwright-report`, `test-results`).\n6. `scripts/try-skill.ts` must load repo root `.env` and pass secrets to child processes via process environment (do not write `.env.local` into run dirs).\n7. `scripts/try-skill.ts` must run Codex fully autonomously inside the run dir, inject the selected skill content into the prompt, and instruct “no commits, only file changes”. Use `--dangerously-bypass-approvals-and-sandbox` so the agent can actually write files and run `npm` on the host filesystem (Codex sandbox can be too restrictive outside trusted git repos).\n8. `scripts/try-skill.ts` must capture all agent output to a transcript file and record wall time, and it must redact any secret values found in `.env` from saved transcripts.\n9. Run the trial: `node scripts/try-skill.ts --skill integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs --starter-project nextjs16`\n10. The script must validate automatically in the run dir by running `npm ci` and `npm run test:e2e`.\n11. If tests fail, or the diff looks wrong, or the agent got stuck repeatedly, or runtime is too long: update the skill (dense + prescriptive), then rerun step 9.\n12. If a high-level assumption was wrong (starter layout, test harness, env loading): update this section in `README.md`, then rerun step 9.\n\nImportant note (skills vs harness):\n- Skills are written as real-world integration guides. They must not require any specific test harness (Vitest/Playwright/etc).\n- E2E validation is an internal quality gate. The harness prompt can require “make `npm run test:e2e` pass” and let the agent add/adjust tests as needed, but that requirement must not live in the skills themselves.\n",
  "bytes": 7234,
  "sha": "712663cc9fe402da5666b8d45b87b07ac545fd67fde37512fbc9d6724e5d0f1b",
  "repo_slug": "transloadit/skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_transloadit_skills_integrate_uppy_transl_04abe033/readme"
}