Skill Fallbacks

Fallback skills are offered only when a needed tool or MCP server is absent.

from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Answer research questions.",
    skills=["./skills/web-via-terminal", "./skills/summarise"],
)
agent.start("Find recent papers on diffusion models.")

The user runs the agent; fallback skills appear in the listing only when required tools or servers are missing.

Quick Start

Declare a fallback in SKILL.md

Add fallback_for_tools or fallback_for_servers to the SKILL.md frontmatter:

---
name: web-via-terminal
description: Fetch web content using terminal when no web tool is available
requires_tools: [terminal]
fallback_for_tools: [web]
---

# Web via Terminal
When the web tool is absent, use terminal commands like curl to fetch content.

The skill appears only when the web tool is not present, and only when terminal is available.

Wire it into an Agent

from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Find information for the user",
    skills=["./skills/web-via-terminal", "./skills/web-fetch"],
)
agent.start("Look up the latest Python release")

If web-fetch provides a web tool → web-via-terminal is hidden.
If only terminal is available → web-via-terminal is offered.

How It Works

Primary tool state	Fallback `requires_*` met?	Skill offered?
Present	Any	No — primary handles it
Absent	Yes	Yes — fallback steps in
Absent	No	No — fallback can’t run either

The skill’s own requires_tools / requires_servers / requires_env gates still apply on top of fallback eligibility. A fallback skill that can’t satisfy its own requirements is still excluded.

Configuration Options

Key	Type	Default	Description
`fallback_for_tools`	`list[str]`	`[]`	Skill is offered only when none of these tool names are present.
`fallback_for_servers`	`list[str]`	`[]`	Skill is offered only when none of these MCP server names are present.
`fallback-for-tools`	`list[str]`	`[]`	Hyphenated alias of `fallback_for_tools`.
`fallback-for-servers`	`list[str]`	`[]`	Hyphenated alias of `fallback_for_servers`.

Both underscore and hyphen forms are accepted. If both are set, the union is used.

Common Patterns

Web fallback via terminal

When a native web tool is absent, let agents use curl through the terminal tool instead:

---
name: web-via-terminal
requires_tools: [terminal]
fallback_for_tools: [web]
---

Local search fallback when no MCP search server is configured

---
name: local-grep-search
description: Search local files using grep when no MCP search server is available
requires_tools: [terminal]
fallback_for_servers: [mcp-search-server]
---

Multiple primary tools — fallback hidden unless all are absent

---
name: lightweight-pdf-reader
requires_tools: [terminal]
fallback_for_tools: [pdf_read, ocr_extract]
---

The fallback is hidden if any of pdf_read or ocr_extract is present.

Best Practices

Pair fallback_for_* with requires_*

A fallback skill that cannot run is still excluded. Always declare the tools the fallback actually needs via requires_tools so the skill manager can gate it properly.

---
name: web-via-terminal
requires_tools: [terminal]        # needs terminal to run
fallback_for_tools: [web]         # only offered when web is absent
---

Keep fallback skill outputs self-explanatory

Fallback skills run in place of a primary capability — their output should be as close as possible to what the primary would produce. Add notes in the skill body describing any known differences.

Don't chain fallbacks

Avoid making a fallback skill declare its own fallback_for_* pointing to another fallback skill. The filter logic is applied once during skill discovery and chaining is not resolved automatically.

Test with the primary absent and present

Verify both paths: that the fallback appears when the primary is absent, and that it disappears when the primary is present.

# Without primary tool
agent_no_web = Agent(
    name="Test",
    instructions="Research topics",
    skills=["./skills/web-via-terminal"],  # web tool not loaded
)

# With primary tool loaded — fallback should be hidden
agent_with_web = Agent(
    name="Test",
    instructions="Research topics",
    skills=["./skills/web-via-terminal", "./skills/web-fetch"],
)

Skill Capability Gates

Declare tool, server, and env requirements — the forward gates that fallbacks complement

Agent Skills

Overview of the skills system and how to write skills

Skill Invocation

How skills are invoked at runtime

Skill Lifecycle

Discover, validate, and activate skills

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Configuration Options

Common Patterns

Web fallback via terminal

Local search fallback when no MCP search server is configured

Multiple primary tools — fallback hidden unless all are absent

Best Practices

Skill Capability Gates

Agent Skills

Skill Invocation

Skill Lifecycle

​Quick Start

​How It Works

​Configuration Options

​Common Patterns

​Web fallback via terminal

​Local search fallback when no MCP search server is configured

​Multiple primary tools — fallback hidden unless all are absent

​Best Practices

​Related

Skill Capability Gates

Agent Skills

Skill Invocation

Skill Lifecycle

Quick Start

How It Works

Configuration Options

Common Patterns

Web fallback via terminal

Local search fallback when no MCP search server is configured

Multiple primary tools — fallback hidden unless all are absent

Best Practices

Related