Reading Time: 15 minutes

This is the second article in the four-part blog series about Headless MuleSoft for developers. In part one, we mapped the three surfaces: Developer Hub, Platform MCP Server, and IDE Skills, and how to choose between them. Now we go one layer deeper: the reliability problem that shows up the moment any agent tries to execute a multi-step workflow, and how MuleSoft Skills fix it.

A Skill is a structured markdown file (SKILL.md) that encodes a multi-step API workflow (step sequencing, cross-service data threading, multiple execution paths, and implementation gotchas) as a fetchable recipe an AI agent loads on demand.

You tell an AI agent: “Secure my Orders API with rate limiting.”

The agent has access to 36 APIs across MuleSoft’s Developer Hub. Hundreds of endpoints. It knows how to call each one individually. But this task requires six coordinated calls across three different services, in a specific order, with the output of each feeding into the next.

Without a Skill, the agent guesses. Maybe it creates the API instance before selecting an environment. Maybe it uses the wrong policy template endpoint and gets back property names that don’t work at apply time.

With a Skill, the agent loads a structured recipe: here are the seven steps, here’s where every input comes from, here are three valid starting points depending on what you already have, and here’s how to verify it worked.

“Secure my API” is seven API calls nobody documented together

The secure-api Skill orchestrates calls across four separate APIs:

  1. Publish to Exchange (urn:api:exchange-experience / createAssets)
  2. List environments (urn:api:access-management / listEnvironments)
  3. Get gateway targets (urn:api:api-portal-xapi / getGatewayTargets)
  4. Create API instance (urn:api:api-manager / createOrganizationsEnvironmentsApis)
  5. Deploy to gateway (urn:api:proxies-xapi / createOrganizations…Deployments)
  6. Browse policy catalog (urn:api:api-portal-xapi / getExchangePolicyTemplates)
  7. Apply policy (urn:api:api-manager / createOrganizationsEnvironmentsApisPolicies)

Each step’s output feeds the next. The environment ID from step 2 becomes a path parameter in step 4. The environmentApiId from step 4 is needed in steps 5, 6, and 7. No single API spec documents this sequence. The OpenAPI definitions for each service are complete in isolation. The workflow that stitches them together lived in tribal knowledge until someone encoded it as a Skill.

What’s in a SKILL.md file

Every Skill is a single markdown file with YAML frontmatter and structured step blocks. From the real setup-agent-scanner Skill:

A trigger description loaded with natural-language phrases for intent matching: 

---
name: setup-agent-scanner
description: |
  Creates a scanner configuration to discover AI agents from external
  platforms like AWS Bedrock, Microsoft Copilot, or Google Vertex AI.
  Use when setting up agent discovery, configuring a new scanner,
  connecting to cloud AI platforms, or importing agents into Anypoint Exchange.
---

The description field does double duty: it documents the Skill’s purpose for humans and provides natural-language phrases for intent matching at runtime. When a user says “set up a scanner for my AWS agents,” the orchestrator matches that intent against each Skill’s description, fetches the matched SKILL.md from the registry, and loads only that workflow into the agent’s context.

And structured steps that specify what to call and how to thread data: 

api: urn:api:agent-scanner-configuration-service
operationId: getTargetSystems
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: getOrganizations
      field: $.id
    description: Your organization's Business Group GUID
outputs:
  - name: targetSystemId
    path: $[*].id
    labels: $[*].name
    description: The target system ID to use when creating a connection

The inputs section declares that organizationId comes from a different API, a specific operation, and a specific JSONPath. The outputs section extracts values by path and names them for downstream steps. The labels field pairs human-readable names with IDs so the agent shows “AWS Bedrock (uuid-abc)” rather than raw GUIDs.

Execution paths: Not everyone starts at step 1

The secure-api Skill defines three entry points: 

- **Full setup**: Steps 1, 2, 3, 4, 5, 6, 7
  - When: You have an API specification and need to publish it first

- **From Exchange asset**: Steps 2, 3, 4, 5, 6, 7
  - When: You already have an Exchange asset

- **Apply policy only**: Steps 2, 6, 7
  - When: You already have an API Manager instance

A developer who already has their API in API Manager skips steps 1 through 5. The Skill tells the agent explicitly which steps to skip, rather than forcing it to infer.

4 input types, zero ambiguity

Every parameter declares its source. From the request-api-access and secure-api Skills: 

# From another API (cross-service resolution)
organizationId:
  from:
    api: urn:api:access-management
    operation: listMe
    field: $.user.organization.id

# From a previous step (data threading)
targetOrganizationId:
  from:
    variable: targetOrganizationId

# User-provided (agent asks)
portalId:
  userProvided: true
  description: Portal ID the user belongs to

# Literal (hardcoded for this workflow)
technology:
  value: "flexGateway"

No “figure out the org ID somehow.” The agent knows before making a single call where every value will come from.

Skills encode the ‘gotchas’ nobody would guess

The most valuable parts of a Skill are the things an agent would get wrong without explicit guidance. From the real secure-api Skill:

  • Step 4: “isCloudHub must be null, not false, or it fails validation.” An agent would reasonably set a boolean to false
  • Step 5: “Use flat top-level fields, NOT the nested target object.” The API accepts both, but the nested form requires undocumented extra fields
  • Step 6: “Use getExchangePolicyTemplates, not listOrganizationsPolicytemplates.” The generic endpoint returns property names that don’t work at apply time
  • Step 7: “Configuration property names differ between gateway types.” Omni Gateway uses credentialsOriginHasHttpBasicAuthenticationHeader; the generic template uses credentialsOrigin. Wrong name, 400 error

These aren’t edge cases. They’re the common path.

How agent skills chain into larger workflows

Skills compose. The setup-agent-scanner Skill ends with “Use the Run Agent Scan and View Results skill to execute immediately.” And run-agent-scan-and-view-results picks up where scanner setup left off: trigger the scan, poll until COMPLETED, fetch discovered agents.

Similarly, discover-portal-apis outputs groupId, assetId, minorVersion, and instanceId, which are exactly what request-api-access needs as inputs. “Find a payments API and request access on the Gold tier” chains both Skills, with outputs from the first flowing into the second.

The catalog

MuleSoft’s Developer Hub publishes 28 Skills:

DomainCountExamples
API and agent security6secure-api, secure-agent, setup-agent-scanner
Portal (consumer flows)6discover-portal-apis, request-api-access
Mule integration10build-mule-integration, secure-mule-app
PDK (policy development)5develop-pdk-policy, pdk-test, pdk-unit
Platform navigation1platform-assistant

Every Skill is fetchable at https://dev-portal.mulesoft.com/skills/{slug}/SKILL.md. Discovery via registry.json or AGENTS.md.

Why not bigger prompts or smarter models

You could put all this in a system prompt. But 28 workflows across 36 APIs would consume most of a model’s context window before the user asks a question. Skills load on demand: match intent against short descriptions, fetch only what’s needed. This on-demand loading pattern aligns with how Agentforce manages context across its agent topics and actions.

You could rely on a smarter model inferring the right sequence. Sometimes it will. But “sometimes” isn’t good enough when null vs. false is the difference between a working deployment and a 20-minute debugging session. Skills encode institutional knowledge that inference can’t recover from a spec alone.

CriterionSystem promptSkill
Context window costAll workflows loaded upfront; scales linearly with workflow countOnly matched workflow loaded; constant per request
MaintainabilityEdit a monolithic prompt; risk breaking unrelated flowsEdit one file per workflow; changes are isolated
ReliabilityModel must infer sequencing and gotchas from proseSteps, data threading, and edge cases are explicit
DiscoverabilityBuried in prompt text; no programmatic lookupIndexed in registry.json; matched by intent at runtime

The layers are complementary:

LayerWhat it provides
OpenAPI specEndpoint signatures and response schemas
MCP toolAgent-callable operation with typed parameters
SkillMulti-step workflow with sequencing, data flow, execution paths, and gotcha documentation

The pattern generalizes

MuleSoft’s Skills target REST APIs, but the problem is interface-agnostic. A GraphQL schema, an AsyncAPI spec, or a CLI’s –help all have the same gap: individual operations documented, multi-operation workflows not. The structural needs are always the same: sequencing with data flow, multiple entry points, typed inputs, verification criteria, and gotcha documentation for the traps inference can’t catch.

If your agents struggle with multi-step workflows, the fix probably isn’t a better model or a longer prompt. It’s encoding the workflow as a structured, fetchable recipe. Skills are one implementation that builds on MuleSoft’s Anypoint Platform and its API-led connectivity approach.

Skills solve the reliability problem for agents working across MuleSoft’s headless surfaces. But what does that actually look like when those agents are running in production such as responding to incidents at midnight, catching a token cost spike before the invoice, surfacing shadow services before they become a governance problem? We’ll explore the platform, the skills, the surfaces – all in motion, in the scenarios that matter most – in the next article. No new concepts to learn; you already have the foundation.

Resources