> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills vs. Direct APIs

> Decide whether an agent should follow a reusable AIsa Skill or call individual APIs with application-controlled orchestration.

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

| Requirement                | Agent Skill                                           | Direct API                                                 |
| -------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| Primary unit               | Complete task or workflow                             | Individual endpoint operation                              |
| Orchestration              | Encoded in reusable instructions and supporting files | Implemented by the application                             |
| Parameter control          | Guided by the Skill                                   | Fully application-controlled                               |
| Reuse across agent clients | High when the client supports the Skill format        | Requires shared application code or SDK wrappers           |
| Inspection                 | Review the Skill instructions and referenced tools    | Review source code, API calls, and schemas                 |
| Custom business state      | Usually supplied by the runtime or application        | Fully controlled by the application                        |
| Maintenance                | Update the Skill when the workflow changes            | Update integration code when contracts or logic change     |
| Best fit                   | Repeatable outcome with a known process               | Product-specific orchestration or precise endpoint control |

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](/docs/agent-skills) and [Skills Quickstart](/docs/agent-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](/docs/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](/docs/by-goal). If the interface is already known, continue with [Capabilities by Interface](/docs/by-interface).

## Related guidance

* [One API for Models, Data, and Agent Tools](/docs/concepts/unified-model-data-tools-api)
* [Pre-built Skills vs. Custom Skills](/docs/guides/learn/agent-skills-vs-tools)
* [AIsa Architecture and Integration Boundaries](/docs/evaluate/architecture)
* [Security Evaluation Guide](/docs/evaluate/security)