Include & Exclude Skills

An agent runs with every skill enabled on its design. To limit a single execution to a subset of those skills, or to leave one out, send the reserved skills input parameter. It is a per-execution filter that applies only to the request carrying it and never changes the agent's design.

The skills parameter

When you execute an agent, you send a list of key/value input parameters. Alongside the agent's own parameters, a set of reserved keys is supported. One of them is skills, whose value is a filter object with two mutually exclusive lists:

Field	Type	Description
include	string[]	Allow-list. Only the listed skill codes remain available for this execution.
exclude	string[]	Deny-list. The listed skill codes are blocked for this execution; every other skill stays available.

Only one of include or exclude may be set in a single request. Each entry is a skill code, not a display name.

Behaviour

skills value	Result
Omitted	All skills enabled on the agent remain available (default behaviour).
include: ["http-request", "prompt"]	Only http-request and prompt are available.
include: [] (empty)	Every user skill is disabled for this execution.
exclude: ["send-email"]	Every skill except send-email remains available.
exclude: [] (empty)	All skills remain available (equivalent to omitting the parameter).

Request examples

Include only specific skills

Limit the execution to the http-request and prompt skills:

cURL — include

curl https://api.serenitystar.ai/api/v2/agent/YOUR_AGENT_CODE/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '[
    { "Key": "message", "Value": "Fetch the latest order status for customer 12345." },
    {
      "Key": "skills",
      "Value": { "include": ["http-request", "prompt"] }
    }
  ]'

Exclude a single skill

Keep every skill available except send-email:

cURL — exclude

curl https://api.serenitystar.ai/api/v2/agent/YOUR_AGENT_CODE/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '[
    { "Key": "message", "Value": "Summarise this ticket and suggest next steps." },
    {
      "Key": "skills",
      "Value": { "exclude": ["send-email"] }
    }
  ]'

Rules and notes

• Do not combine include and exclude in the same request. Set one or the other.
• The filter is per execution. It never modifies the agent's saved skill configuration.
• An empty include list disables every user skill.
• Skill codes are validated. Passing a code that is not a valid skill rejects the execution with an error.

For the full request and response schema, see the Execute agent endpoint in the API reference.