Skip to main content
An Agent Skill packages task-oriented instructions, tool selection, workflow steps, safety notes, and output guidance. A direct API integration gives the application explicit control over endpoints, parameters, sequencing, retries, and state. Both can use the same underlying AIsa capabilities. The choice is primarily about who owns orchestration and how reusable the workflow should be.

​
Side-by-side comparison

A Skill is not automatically a hosted service or an opaque agent. It is a portable instruction bundle that teaches a compatible runtime how to perform a task with documented capabilities.

​
Use an Agent Skill when

Prefer a Skill when:
  • The user asks for an outcome rather than a specific endpoint.
  • The workflow is repeated across projects or agent clients.
  • Tool selection and sequencing should follow a consistent method.
  • Evidence rules, safety checks, and output structure should travel with the workflow.
  • An existing Skill already covers the task and can be reviewed before use.
Start with the Agent Skills catalog and Skills Quickstart.

​
Use direct APIs when

Prefer direct APIs when:
  • The application must choose exact endpoints and parameters.
  • Request timing, caching, pagination, retries, or fallback behavior is product-specific.
  • Data must be normalized into an internal schema.
  • The workflow depends on proprietary business rules or internal state.
  • Every external call must be represented explicitly in application code and observability.
Start with the API Reference and load only the endpoint pages required for the task.

​
Combine them when appropriate

The two approaches are complementary. A Skill can define the process while direct APIs provide the individual operations. For example, a research Skill may instruct the agent to:
  1. Clarify the research question.
  2. Call specific search or data APIs.
  3. Preserve source URLs and retrieval times.
  4. Use a model for synthesis.
  5. Label unsupported claims and missing evidence.
The Skill owns the reusable method. The APIs still define the exact requests and responses.

​
Read, write, and payment boundaries

Neither interface removes the need to classify operations:
  • Read: retrieve information without changing an external system.
  • Write: create, send, publish, update, delete, follow, or otherwise change external state.
  • Payment: incur a billable runtime purchase or initiate a financial transaction.
A Skill that references a write or payment operation does not grant permission to execute it. Before side effects:
  1. Verify the connected identity and authorization.
  2. Display the target and intended effect when confirmation is required.
  3. Apply the narrowest permission and operation.
  4. Avoid unbounded or ambiguous retries.
  5. Verify the external result and usage record.

​
Decision checklist

Choose the interface by asking:
  • Is the task a reusable outcome or a product-specific integration?
  • Who should own endpoint sequencing and task state?
  • Does the application need exact parameter and retry control?
  • Will multiple agent clients reuse the same instructions?
  • Are any operations writes or payments?
  • How will the workflow be tested, reviewed, and updated?
If the task is described by its desired outcome, start with Capabilities by Goal. If the interface is already known, continue with Capabilities by Interface.