Skills

A skill is a reusable workflow, written as a SKILL.md file and stored on the Computer. Ask Pine's skill author to draft one from a turn the agent completed or from a person's demonstration, review the draft, then activate it. Every session's agent on that Computer can then use it. A skill describes the pages involved, the steps, and the errors to watch for.

The examples use the Ruby SDK.

The SKILL.md format

A skill is a Markdown file with YAML frontmatter. Pine's skill author writes it, and you read it before agents use it. A typical skill:

---
name: book-x-supplier-flight
description: "Book a flight on the X Supplier portal: sign in, search, hold a seat, confirm."
origin: "book.x-supplier.example"
---

# Booking a flight on X Supplier

## When this skill applies
- The goal is to book a flight, and the site is book.x-supplier.example.

## Steps
1. Open /portal/login. The SSO button is in the top right.
2. After SSO, open the "Travel" tile on the dashboard.
3. Search with MM/DD/YYYY dates and IATA airport codes.
4. "Hold seat" is a soft confirmation. The booking happens on the next
   page, with the "Confirm" button.

## Watch for
- A captcha on the SSO page: ask a person to take over.
- A "Hold expired" banner: holds last 10 minutes. Start again from the search.

name identifies the skill on the Computer. description helps an agent pick the right skill from a list. origin records the site the skill was learned on; it's for your records and doesn't limit where the skill is used. The body is the workflow itself.

How a skill becomes active

1. You ask for a draft with learn, teach or refine, or upload a SKILL.md you wrote.
2. The draft is saved as a new pending version of the skill.
3. You read the draft's SKILL.md.
4. You activate that version, and agents use it from then on.

A version's status is pending (a draft waiting for review), active (served to agents), inactive (deactivated, or replaced by another version) or deleted (kept for audit). Drafting never activates a skill. Review is the safeguard: a skill steers other agents through your systems, so a person reads it before any agent does.

Draft a skill

There are two ways to ask Pine's skill author for a draft:

• session.learn drafts from the session's latest turn. The skill author reads what the agent did and writes a SKILL.md for it. The turn must have finished as completed. No demonstration is needed.
• session.teach(goal:) drafts from a person's demonstration. A person takes control of the session, performs the flow and releases control, which completes a handoff. Use it for workflows the agent couldn't work out alone. The draft is marked tainted, because a demonstration may touch a sign-in, MFA or payment field.

# Draft from the agent's turn:
session.agent.run("Book a flight from SFO to JFK next Tuesday on X Supplier.")
# ... wait for the turn to complete ...
result = session.learn        # waits for the skill author to finish
result.learned?               # true when a draft was saved
result.draft                  # the new version's record: name, version, status "pending"
result.reason                 # why no draft was written, when learned? is false

# Draft from a person's demonstration:
computer.take_control(name: session.name)
# ... the person performs the flow on the desktop ...
computer.release_control(name: session.name)
demo = session.teach(goal: "Book a flight on X Supplier.")
if demo.needs_clarification?
  demo = demo.clarify("The 'Hold seat' button is a soft confirmation.") # answers demo.questions
end
demo.taught?                  # true when a draft was saved; demo.draft is its record

result.draft is the version's record (its name, version number and status), not its text. Read the text from the drafts list below.

teach uses the session's latest handoff unless you pass handoff_id:. A session keeps its five most recent handoffs for 24 hours; list them with session.handoffs(limit:, before:), which returns next_before when older ones remain. With no handoff to learn from, teach returns 409 /errors/handoff-unavailable.

learn and teach wait while the skill author works, usually 30 seconds to 3 minutes. They raise PineSandbox::Error if the author run fails, is canceled, or is interrupted by a restart of the Computer's services; retry in the last case. To start a run without waiting, see Run the skill author without waiting. Agent: skill author runs explains how author runs relate to the agent's event stream.

Review and activate

The Ruby SDK manages skills on the Computer through computer.skills:

computer.skills.drafts                                # pending drafts, each with its SKILL.md body
computer.skills.activate("book-x-supplier-flight", version: 1)
computer.skills.deactivate("book-x-supplier-flight")
computer.skills.list                                  # Pine's skills and your active ones, with `enabled` for each
computer.skills.get("book-x-supplier-flight")         # metadata and the full SKILL.md
computer.skills.versions("book-x-supplier-flight")    # versions not deleted, metadata only
computer.skills.version("book-x-supplier-flight", version: 1) # one version with its SKILL.md
computer.skills.delete("book-x-supplier-flight", version: 1)  # remove a version; stops serving it if active

In the Console, the Playground's Skills tab shows the same drafts, active skills and inactive versions, so a person can read a draft and activate it there. It uses the same routes.

A skill is served only after you activate it. A draft steers no agent: an unreviewed skill could carry assumptions that harm later runs. Activation updates what the Computer's agents are offered before the call returns. An unknown version returns 404, a deleted one 410, and activating more skills than the Computer's limit allows 409. Replacing an active version removes the old copy first, so a failure partway can leave the skill unserved until you activate it again, which is safe to retry. Deactivating keeps the versions, so you can activate one again; a turn already running keeps instructions it has loaded. computer.skills.get returns the text of your active skills; Pine's skills are listed by name and description only.

How agents use active skills

You can let the agent find a skill, or select one for a run.

Discovery

Pine's agent sees the name and description of every active skill and follows one when the goal matches. It sees "book-x-supplier-flight: Book a flight on the X Supplier portal" and uses it for a goal about booking on X Supplier. Activate a skill, and later runs find it with no code change.

Selection with run(skills:)

When your application already knows which skill a run needs, select it:

session.agent.run(
  "Book a flight from SFO to JFK for Tuesday.",
  skills: ["book-x-supplier-flight"],
)

The agent receives each selected skill's full workflow as required guidance for the run, not as a suggestion.

• Selection lasts for the run. It still applies after you answer a question. A steer doesn't change it, and each run selects again.
• Other active skills stay available, with or without skills:.
• Memory belongs to the session. A later run may recall a skill used earlier. Call session.agent.reset before unrelated work if you want a clean start.
• Only active learned skills can be selected. Pine's own skills, inactive skills and unknown names are rejected with 400.

Start from a scaffold

learn and teach take an optional scaffold:, a starting SKILL.md of up to 32 KiB. The skill author keeps its structure (frontmatter, headings, parameter names) and fills in the body. Use it when you already know the shape of the workflow and want the skill author to fill in the details:

scaffold = <<~MD
  ---
  name: file-quarterly-expense
  description: "File a quarterly expense in the internal portal."
  ---

  # Steps
  1. Open expense.internal.example
  2. ...
MD
session.teach(goal: "File a quarterly expense.", scaffold: scaffold)

An empty scaffold means no scaffold. clarify sends the same scaffold again in the clarification round.

Refine or upload a skill

session.start_refine(skill:, version:, guidance:) revises an existing version from a plain-language instruction of up to 64 KiB, such as "make the date a parameter". The version's SKILL.md is the starting point. If the session has a completed turn, the skill author also uses what that turn did as evidence, so choose the session you refine from. The result is a new pending version of the same skill; a draft whose name or origin doesn't match the original is refused.

session.author_skill(name:, skill_md:, reason:) registers a SKILL.md you wrote yourself. Its frontmatter name must match name. The text is checked for anything that looks like a secret (422 if it finds one) and saved as a pending version.

Run the skill author without waiting

The Ruby SDK also starts author runs without waiting for them:

started = session.start_learn                  # also start_teach(goal: ...) and
                                               # start_refine(skill: ..., version: ..., guidance: ...)
author_id = started["author_session"]
# ... later, if you need to stop it:
session.cancel_author(author_id: author_id)

start_teach also takes handoff_id:, clarifications: and scaffold:, and start_learn takes scaffold:.

Each start call returns the 202 response (author_session, task_id, and handoff_id for teach) at once. Follow the run at /v1/sessions/{name}/skills/author/{author_id}/events, with author_session as author_id. The stream ends with one result event whose terminal_reason is draft_registered, clarification_requested, not_reusable, registration_failed, canceled, failed or coordinator_restarted (the Computer's services restarted; start the run again); its author holds the new draft, or the questions and handoff_id to answer. cancel_author returns canceled: false when the run had already finished.

Use these from a web request handler behind a proxy with a short timeout, where waiting minutes for the skill author isn't possible. learn and teach suit callers that can wait: command-line tools, background workers and tests.

Pine's skills

The Computer also carries skills Pine provides. computer.skills.list shows them with origin: "pine", including ones switched off (enabled: false). Those marked switchable (for example pdf or docx) can be switched off. Switch a skill off when your tasks never need it, so the agent isn't offered it:

computer.skills.set_enabled("pdf", false)

The switch belongs to the Computer and, like the rest of its saved state, survives stop and start unless the Computer is ephemeral. It applies to the agents the Computer starts next. For a session whose agent is already running, call session.agent.reset, which also clears that session's conversation. enabled in the listing reports what the next agent is offered. A Pine skill that isn't switchable is refused with 400; your own skills use activate and deactivate instead.

To see which product features this Computer can use and the limits it applies, read computer.capabilities.

API reference

The skill routes are in the Computer API. Drafting, reviewing and activating (/v1/sessions/{name}/learn, /teach, /refine, /skills/author/{author_id}/events, /v1/skills/drafts, /v1/skills/{name}/activate) are under Skills. The skill listing, Pine skill switches and capabilities (/v1/skills, /v1/skills/{name}, /v1/skills/{name}/enabled, /v1/capabilities) are under Agent.