Skill anatomy

A skill is a YAML file with a defined structure. It specifies inputs, a sequence of steps, and outputs. Skills are stateless and reusable.

Minimal skill

name: check-feed-freshness
version: "1.0"
description: "Returns whether a named PlexiFact feed was updated within the specified window."

inputs:
  feed_name:
    type: string
    required: true
  max_age_minutes:
    type: integer
    default: 30

outputs:
  is_fresh:
    type: boolean
  staleness_minutes:
    type: integer

steps:
  - action: plexifact.catalog.get_feed_metadata
    args:
      feed: "{{ inputs.feed_name }}"
    capture: meta
  - action: core.time.diff_minutes
    args:
      from: "{{ meta.last_ingested_at }}"
      to: "{{ now() }}"
    capture: age
  - action: core.logic.set_output
    args:
      is_fresh: "{{ age <= inputs.max_age_minutes }}"
      staleness_minutes: "{{ age }}"

Frontmatter fields

Field	Type	Required	Description
name	string	Yes	Unique identifier. Used in agent task references. Snake_case convention.
version	string	Yes	Semantic version string. Must increment when inputs or outputs change.
description	string	Yes	One sentence. Used in the skill library index and audit logs.
tags	string[]	No	Categorization for the skill library browser. E.g., ["data", "plexifact", "monitoring"]
deprecated	boolean	No	If true, Flexor logs a warning when the skill is invoked and suggests a replacement.
replaces	string	No	Name of the skill this one supersedes. Shown in the deprecation warning.

Input schema

Each input field in the inputs map has:

Sub-field	Type	Required	Description
type	string | integer | number | boolean | array | object	Yes	Data type.
required	boolean	No	If true, agent will error if the argument is not provided. Defaults to false.
default	any	No	Value used when the argument is not provided and required is false.
description	string	No	Shown in skill library documentation.
enum	any[]	No	Restricts the value to one of the listed options.

Step types

action step

Invokes a named action from the standard library or a custom action registered in the vault.

- action: plexifact.catalog.get_feed_metadata
  args:
    feed: "{{ inputs.feed_name }}"
  capture: result_variable

The capture key assigns the action’s return value to a variable available in subsequent steps.

condition step

Evaluates a boolean expression. If false, the step and all steps until the next end_condition are skipped.

- condition: "{{ !result_variable.is_fresh }}"
- action: core.notify.slack
  args:
    message: "Feed is stale."
- end_condition

loop step

Iterates over a list.

- loop: "{{ inputs.feed_names }}"
  as: feed
  do:
    - action: check-feed-freshness
      args:
        feed_name: "{{ feed }}"
      capture: result

call step

Invokes another skill by name. This is how skills compose.

- call: data-freshness-check
  args:
    feed_name: "equity-prices"
  capture: freshness

Template syntax

Step arguments use Jinja2-style template syntax:

• {{ inputs.field_name }} - reference an input
• {{ captured_variable.property }} - reference a captured value
• {{ now() }} - current UTC timestamp (ISO-8601)
• {{ env("VARIABLE_NAME") }} - read from environment (use sparingly; prefer vault.json references)

Output schema

Each output field in the outputs map has the same structure as inputs: type, description. Outputs are populated by the final core.logic.set_output step or by steps that write directly to named outputs.

Trigger keywords

Trigger keywords are metadata that help the system understand when a skill is appropriate. They are used by agents when auto-selecting skills for a use case and by the knowledge base for context matching.

trigger_keywords:
  - "data freshness"
  - "feed staleness"
  - "ingestion delay"
  - "monitoring"

This field is optional but improves discoverability in the skill library.