Skills

A skill is a reusable, sandboxed serverless function that an agent can call as a tool during a workflow run. Skills encapsulate discrete, testable capabilities — fetching data from an API, transforming a payload, validating a schema, calling an integration — and expose them to agents through a defined JSON Schema input interface. Where agents are probabilistic, skills are deterministic: the same input reliably produces the same output.

Skills can also be used directly as steps of kind skill in a workflow, independent of any agent. In that mode, the workflow maps inputs to the skill's schema and the skill executes as a standard step.

---

When to use skills

Use a skill when:

• You have a repeatable operation with a well-defined input and output that an agent should be able to invoke
• You want a unit-testable, versioned piece of logic that can be used across multiple agents and workflows
• You need an integration with an external service that requires stored connection credentials
• You want to isolate sensitive operations (API calls, data transformations) in a sandboxed environment away from the agent's general execution context

Do not use a skill for complex, context-dependent reasoning. Use an agent step for that. Skills work best for concrete, bounded tasks.

---

Key concepts

Sandbox execution — every skill runs in an isolated the platform sandboxed environment. The skill has no access to other workspace resources, other runs, or the broader ProvenanceOne infrastructure beyond what is passed in its input and what its optional connection credential provides. This isolation limits the blast radius of a misbehaving skill.

Input schema — every skill defines a JSON Schema that describes its expected inputs. ProvenanceOne validates the input against the schema before invoking the skill. If validation fails, the skill step fails immediately with a schema validation error — the skill code is never called.

Connection — skills can optionally be linked to a workspace connection. The connection injects credentials (OAuth token, API key, etc.) into the skill's execution environment at runtime. The credential is never included in the skill package itself.

Trust level — like agents, skills have a trust level: low, medium, or high. Trust level affects how the platform treats the skill's outputs when used in an agent's tool call chain. Lower trust may trigger additional validation or logging.

Package — a skill is distributed as a .zip archive uploaded to object storage via a pre-signed URL. The packageKey field records the storage object key. The package must include all dependencies.

---

How it works

Upload flow

1. Call POST /skills/{id}/upload-url to get a pre-signed upload URL.
2. Upload your .zip package to the URL using an HTTP PUT.
3. Once the upload completes, the skill is ready. The packageSize field updates to reflect the uploaded package.

The skill package should include your handler function and all dependencies. ProvenanceOne executes the handler in a execution runtime.

Note: The runtime environment (Node.js version, Python version, etc.) is determined by the skill configuration. Ensure your package targets the correct runtime.

Input validation

When a skill is invoked — either as a workflow step or as a tool call from an agent — ProvenanceOne validates the provided input object against the skill's inputSchema. Validation failures produce an immediate, descriptive error and do not consume function execution time.

Testing a skill

Use POST /skills/{id}/run to invoke the skill directly with a test payload. The response includes the skill's output, execution time, and any logs emitted during the run. Use this endpoint before attaching the skill to agents or production workflows.

Attaching to agents

Attach a skill to an agent on the agent configuration page under Tools → Skills. The skill appears in the agent's tool list. The agent decides when and whether to call the skill based on its task context. You can attach multiple skills to a single agent.

---

Configuration options

Field	Type	Required	Default	Description
skillId	string	—	auto	Unique identifier (skill_*), assigned by the platform
name	string	Yes	—	Internal identifier
displayName	string	Yes	—	Human-readable name shown in the UI
description	string	No	—	Short description
longDescription	string	No	—	Full description for the detail page
category	enum	Yes	—	data | transform | api | integration
trust	enum	Yes	low	low | medium | high
status	enum	—	active	active | paused
owner	string	Yes	—	Owner user email
team	string	No	—	Team the skill belongs to
tags	string[]	No	[]	Free-form tags
connectionId	string	No	—	Optional connection ID to inject credentials
inputSchema	object	Yes	—	JSON Schema describing accepted inputs
packageKey	string	—	auto	storage object key of the uploaded .zip package
packageSize	integer	—	auto	Size of the uploaded package in bytes

Skill categories

Category	Purpose
data	Read or write structured data; database queries, data lookups
transform	Transform, reshape, or validate a data payload
api	Call an external REST or GraphQL API
integration	Interact with a specific third-party platform (CRM, ticketing system, etc.)

---

Performance metrics (read-only)

Field	Description
runs30d	Number of times this skill was invoked in the last 30 days (also reported as usageCount)
successRate	Percentage of invocations that completed without error
avgLatencyMs	Average execution time in milliseconds

---

Examples

CSV data extraction skill

• category: data
• trust: medium
• inputSchema: { "type": "object", "properties": { "s3Key": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } } } }
• Reads a CSV file from object storage, filters to specified columns, and returns a JSON array
• Used in a scheduled data sync workflow before an agent enrichment step

API integration skill

• category: api
• trust: medium
• connectionId: references a Salesforce OAuth connection
• inputSchema: { "type": "object", "properties": { "accountId": { "type": "string" } } }
• Fetches a Salesforce account record by ID
• Attached to a customer support triage agent so the agent can look up account details without direct API access

Payload schema validator

• category: transform
• trust: high
• No connection required
• inputSchema: { "type": "object", "properties": { "payload": { "type": "object" }, "schema": { "type": "object" } } }
• Validates an arbitrary payload against a provided JSON Schema and returns a validation report
• Used as a guardrail step after agent output before an action step

See /templates/tool-permission-matrix for guidance on matching skill trust levels to workflow risk profiles.

---

Common mistakes

• Not validating skill output in the workflow. Skills can fail or return unexpected data. Add a logic step or validation skill after a skill step for production workflows.
• Including credentials in the skill package. Credentials belong in a workspace connection, not in the .zip package. The connectionId field injects credentials at runtime.
• Uploading a package that exceeds package size limits. serverless function has a deployment package size limit. Keep packages lean; use layers for large shared dependencies.
• Setting trust: high on a skill that calls external services without output validation. High trust skill outputs may bypass some validation gates. Validate externally sourced data explicitly.
• Skipping POST /skills/{id}/run tests. Always test a skill with representative inputs before attaching it to an agent or deploying to production.

---

Troubleshooting

Skill step failing with input validation error — the input passed to the skill does not conform to the inputSchema. Check the step's input mapping in the workflow editor and verify the upstream step's output shape matches the schema.

Skill returning unexpected results — use POST /skills/{id}/run to invoke the skill directly with the exact input from the failed run. Check the skill's logs for internal errors.

Skill step timing out — the function execution timed out. Check whether an external API the skill calls is responding slowly. Consider increasing the function timeout in the skill configuration or adding retry logic in the skill code.

Paused skill — a skill with status: paused cannot be invoked. Reactivate it from the Skills page before running workflows that depend on it.

Upload URL expired — pre-signed upload URLs expire after a short window. If the upload fails with an expiry error, request a new URL via POST /skills/{id}/upload-url and retry.

---

Security and permissions

• editor and admin can create, edit, upload, and test skills.
• viewer can view skill configuration and metrics.
• Skills execute in isolated sandboxed environments. They cannot access other workspace resources except through the provided input and the injected connection credential.
• Connection credentials injected at runtime are sourced from the secrets vault. The skill code receives the credential value, but it is never stored in the skill package or returned in API responses.
• Skill invocations are logged in the run debugger under the tool call record for the invoking agent step.

---

Related pages

• Agents
• MCP Servers
• Workflows

---

FAQ