Key Concepts

Essential concepts and terminology for understanding the Skill Adapter Protocol

Core Concepts

Skill Adapter Protocol (SAP)

A systematic methodology for creating AI agents that can understand and operate within any digital platform through observation, learning, and adaptation.

SAP File (.sap.md)

A markdown document containing structured skill definitions, workflows, and metadata that serves as an AI agent's Standard Operating Procedure for a specific platform and role.

Skill Definition

A structured description of a specific capability, including YAML metadata, numbered steps, UI mappings, conditionals, and error handling procedures.

Role Orchestrator

The coordination system within a SAP file that manages workflow sequences, conditional logic, error handling, and success metrics for a specific role.

The Three Phases

Learn Phase

Observation

The AI agent passively explores the target platform, documenting UI elements, user flows, and interaction patterns without executing any actions.

Key Activities
  • • UI element identification
  • • Flow documentation
  • • Skill mapping
  • • Screenshot capture
Output
  • • Structured markdown report
  • • UI element inventory
  • • Skill-to-UI mappings table
  • • Strategic insights

Translate Phase

Synthesis

The Learn phase observations are synthesized into a complete, executable SAP markdown file with structured skills and workflows.

Key Activities
  • • Skill definition creation
  • • YAML metadata structuring
  • • Workflow sequence design
  • • Error handling setup
Output
  • • Complete SAP markdown file
  • • Executable skill definitions
  • • Role orchestrator configuration
  • • Success metrics framework

Execute Phase

Deployment

The generated SAP file is loaded and executed, with the AI agent performing tasks while maintaining persistent state tracking and adaptive error recovery.

Key Activities
  • • SAP file parsing and loading
  • • Task execution with checklists
  • • Real-time state management
  • • Performance monitoring
Output
  • • Updated task checklists
  • • Execution logs and metrics
  • • Error reports and recovery
  • • Performance summaries
Technical Components

UI Affordances

The interactive capabilities that a user interface provides, such as clickable buttons, input fields, and navigation elements.

Example:
• Button: "Post" → Opens composer
• Input: "Search" → Enables query entry
• Link: "Profile" → Navigates to user page

Skill Mappings

The connection between high-level role capabilities and specific UI interactions required to execute them.

Example:
• trend_monitoring → Trending section
• post_content → Compose button
• engage_audience → Reply/Like buttons

Workflow Sequences

Ordered chains of skills that represent common task patterns for a specific role on a platform.

Example:
Daily: trend_monitoring → content_creation → audience_engagement

Conditional Logic

Decision-making rules that allow agents to adapt their behavior based on current conditions or performance metrics.

Example:
If engagement_rate < 20%, prioritize monitoring
Design Principles

Observability

All agent actions should be transparent, logged, and traceable for debugging and optimization.

Adaptability

Skills should be flexible enough to handle minor UI changes without complete re-learning.

Safety

Include test modes, retry limits, and compliance checks to prevent harmful or unwanted actions.

Modularity

Skills should be independent and reusable across different workflows and contexts.

Safety & Ethical Considerations

SAP implementations must prioritize responsible AI practices and platform compliance.

Platform Compliance

  • • Respect terms of service and usage policies
  • • Implement rate limiting and respectful automation
  • • Avoid actions that could be considered spam or abuse
  • • Include proper attribution and transparency

User Privacy

  • • Minimize data collection and storage
  • • Implement secure credential handling
  • • Provide clear consent mechanisms
  • • Enable user control and data deletion