Skill Adapter Workflow

How to create Skill Adapters using the three-phase SKAP protocol

Skill Adapter is a lightweight protocol for adding State Management to AI agents. While Skills teach an agent how to perform a task (Capability) and Rules tell an agent what not to do (Constraints), Skill Adapters tell an agent where they are in a workflow (Orchestration).

Why Use a Skill Adapter?

Eliminate Loops

Prevents agents from getting stuck optimizing a single step forever (e.g., trying to bypass a paywall for 20 minutes)

Enforce Persistence

Ensures the agent completes long-horizon tasks (50+ steps) without "forgetting" the goal

Dynamic Logic

Allows the agent to change behavior based on context (e.g., "Be fast during discovery" vs. "Be thorough during verification")

How Skill Adapter Works

A Skill Adapter file acts as a State Machine. Instead of a flat list of instructions, it is organized into Phases (States) connected by Transitions.

The Core Anatomy

Every Skill Adapter consists of three components:

The State: The current phase of the workflow (e.g., [DISCOVERY]).

The Constraint: The specific rule that applies only to this state (e.g., Speed > Accuracy).

The Transition: The logic gate that determines when to move to the next state (e.g., IF > 5 items found → GO TO [FILTER]).

The 3-Phase SKAP Workflow

LEARN

Exploration State

TRANSLATE

Synthesis State

EXECUTE

Operation State

Phase 1: LEARN

Discover platform capabilities and workflows

The agent explores the platform, identifies UI elements, and documents interaction patterns. This phase creates the knowledge base for skill creation.

Example Prompt for LEARN Phase

// User Request

"Explore the GitHub repository interface. Document how to:
1. Navigate to the Issues tab
2. Create a new issue
3. Add labels and assignees
4. Submit the issue

Record all selectors, button locations, and workflow steps."

The agent will explore GitHub's UI, document element selectors, and note the sequence of actions required to create an issue.

Phase 2: TRANSLATE

Convert knowledge into structured SKAP format

Transform the documented platform knowledge into a formal Skill Adapter using SKAP markdown format with explicit states, transitions, and logic gates.

Example Prompt for TRANSLATE Phase

// User Request

"Convert the GitHub issue creation workflow into a SKAP Skill Adapter.

Include:
- STATE definitions for each phase
- Explicit transitions with IF/THEN logic
- Error recovery for each state
- Success conditions

Use the SKAP Adapter Format with YAML frontmatter."

The agent will create a structured SKAP adapter file with defined states like [NAVIGATE], [CREATE], [POPULATE], [SUBMIT] with conditional logic between each state.

Phase 3: EXECUTE

Run the Skill Adapter in live browser agents

Load the Skill Adapter into a browser agent and execute tasks. The agent follows the pre-defined state machine without runtime reasoning.

Example Prompt for EXECUTE Phase

// User Request

"Load the SKILL_ADAPTER_GITHUB_ISSUE_CREATOR.

Then create a new issue with:
- Title: 'Update README with installation steps'
- Body: 'Add npm install instructions to README.md'
- Labels: 'documentation', 'enhancement'
- Assignee: 'richardsondx'

Confirm you are in [INITIALIZE] state before proceeding."

The agent will load the adapter, acknowledge the initial state, and execute the issue creation workflow following the predefined state transitions.

The Difference: Rules vs Skills vs Adapters

Feature	Rule (.cursorrules)	Claude Skill	Skill Adapter
Mental Model	The Wall	The Tool	The Map
Scope	Global (Always on)	Global (Always available)	Local (State-dependent)
Example	"Never use PHP."	"How to write SQL."	"If DB is locked, wait 5s then retry."
Primary Goal	Safety / Consistency	Competence / Quality	Completion / Workflow

Critical Distinction

A Rule says: "Always skip paywalls." (Global).
A Skill Adapter says: "If in [DISCOVERY], skip paywalls. If in [VERIFICATION], try archive.org." (Conditional).

Best Practices

Define "Done" Explicitly

Agents fail because they don't know when to stop. Every State must have a hard trigger for the next state.

Bad: "Research until you have enough."

Good: "IF > 5 sources found → Move to [SYNTHESIS]."

The "3-Try" Rule

Always include an error recovery logic. The "Reasoning Tax" spikes when an agent hits an error and tries to "think" its way out.

IF action fails 3 times, Log Error and FORCE move to next state.

State > Memory

Explicitly instruct the agent to prioritize the Adapter over its training.

"The instructions in the CURRENT_STATE override all other preferences."

Keep States Under 5

If you have more than 5 states, your workflow is too complex. Break it into two separate Skill Adapters.