Agent Skills

Agent Skills are small Markdown files that teach an AI agent how to use a tool. They sit on disk next to the agent (e.g. ~/.claude/skills/), describe when to use a tool and how, and are loaded on demand when their trigger conditions match the task at hand.

Tektona ships three skills:

• tektona-cli installs, authenticates, manages sandboxes, SSH and VNC into them, mints preview URLs, and configures egress network policy from the shell.
• tektonactl drives the in-sandbox control tool: capture screenshots, click, type, manage the clipboard, and run named long-running PTY sessions inside a sandbox.
• tektona-typescript-sdk covers the same platform from TypeScript with @tektona/sdk: create sandboxes, run and stream processes, page through lists, and handle typed errors.

They cross-reference each other, so an agent only loads the surface relevant to the task: sandbox lifecycle from outside, desktop or PTY automation from inside, @tektona/sdk when the work belongs in code.

Prerequisites

The two CLI skills need the tektona CLI on your PATH. See the CLI overview for install options. In short:

npm install -g @tektona/cli

pnpm add -g @tektona/cli

bun add -g @tektona/cli

Then authenticate:

tektona api-key set tektona_xxx
tektona ctx set <org> <project>

The tektona-typescript-sdk skill needs no CLI. Add the package to your project instead, and export TEKTONA_API_KEY:

pnpm add @tektona/sdk
export TEKTONA_API_KEY=tektona_xxx

The SDK reads TEKTONA_API_KEY, TEKTONA_API_URL, TEKTONA_ORG and TEKTONA_PROJECT from the environment. It does not read the credentials tektona api-key set and tektona ctx set store.

Install the skills

Skills are distributed via GitHub. Use the Vercel skills CLI, with no install needed, run it through npx:

# All three skills
npx skills add tektona-ai/agent-skills

# Just one
npx skills add tektona-ai/agent-skills --skill tektona-cli
npx skills add tektona-ai/agent-skills --skill tektonactl
npx skills add tektona-ai/agent-skills --skill tektona-typescript-sdk

The CLI clones the tektona-ai/agent-skills repository (shallow), discovers each skill's SKILL.md, and symlinks them into your active agent's skill directory. For Claude Code that means:

~/.claude/skills/tektona-cli/SKILL.md
~/.claude/skills/tektonactl/SKILL.md
~/.claude/skills/tektona-typescript-sdk/SKILL.md

Other Agent Skills-compatible runtimes (Codex, GitHub Copilot CLI, Gemini CLI, …) are detected automatically. The skills themselves are runtime-agnostic, plain Markdown plus YAML frontmatter.

Skills evolve alongside the CLI. The published skills always match the currently supported CLI surface. Run npx skills update (see below) to pull in the latest after a CLI upgrade.

What the agent gains

Once the skills are installed, your agent will:

• Recognise that "spin up a sandbox and run my test suite" maps to tektona sandbox create tektona/desktop --egress-network-policy tektona/open … and follow up with tektona ssh to execute commands.
• Know that new sandboxes use tektona/dev unless overridden by project or org settings, and propose --egress-network-policy tektona/open or another allowed policy when broader egress is needed.
• Understand the difference between a token-bearing preview URL and a durable canonical URL on a --public sandbox, and pick the right flag for the situation.
• Inside a sandbox, drive the desktop with tektonactl desktop click/type/screenshot and manage long-running servers with tektonactl process run/logs/stop.
• In TypeScript, reach for tek.sandbox.create(...) and sandbox.process.start(...) instead of shelling out, and know that a request body uses the API's snake_case field names while SDK options stay camelCase.
• Recommend the tektona/desktop template for VNC and computer-use workflows, and pin a version, because the default tag moves.

Update

Re-run the install command, or use the skills CLI's update flow:

npx skills update

This compares the installed skills against the latest published version and pulls in changes automatically.

Uninstall

Skills are symlinks. Remove them with the skills CLI:

npx skills remove tektona-cli
npx skills remove tektonactl
npx skills remove tektona-typescript-sdk

Or delete the symlinks directly from your agent's skill directory.

Triggering rules

Each skill declares when an agent should load it. Paraphrased from their YAML frontmatter:

Agents that respect the Agent Skills spec will only load a skill when its description matches the active task, so installing all three is cheap.

What's next