> ## Documentation Index > Fetch the complete documentation index at: https://docs.fased.ai/llms.txt > Use this file to discover all available pages before exploring further. # Skills # Skills Fased uses **[AgentSkills](https://agentskills.io)-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Fased loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence. ## Locations and precedence Skills are loaded from several sources: 1. **Extra configured folders and plugin skill folders**: `skills.load.extraDirs` in `~/.fased/fased.json` plus enabled extension skill directories 2. **Bundled skills**: shipped with the install or app bundle 3. **Managed/shared skills**: `~/.fased/skills` 4. **User AgentSkills**: `~/.agents/skills` 5. **Project AgentSkills**: `/.agents/skills` 6. **Agent workspace skills**: `/skills` If a skill name conflicts, precedence is: `/skills` (highest) → `/.agents/skills` → `~/.agents/skills` → `~/.fased/skills` → bundled skills → extra/plugin folders (lowest). ## Per-agent vs shared skills In **multi-agent** setups, each agent has its own workspace. That means: * **Per-agent skills** live in `/skills` for that agent only. * **Shared skills** live in `~/.fased/skills` (managed/local) and are visible to **all agents** on the same machine. * **Shared folders** can also be added via `skills.load.extraDirs` (lowest precedence) if you want a common skills pack used by multiple agents. If the same skill name exists in more than one place, the usual precedence applies: workspace wins, then managed/local, then bundled. ## Plugins + skills Plugins can ship their own skills by listing `skills` directories in `fased.plugin.json` (paths relative to the plugin root). Plugin skills load when the plugin is enabled. They share the lowest precedence tier with `skills.load.extraDirs`, so bundled/shared/workspace copies can override them by name. You can gate them via `metadata.fased.requires.config` on the plugin’s config entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the tool surface those skills teach. ## Plugin Catalog (install + sync) The plugin catalog is the public skills registry for Fased. Use it to discover and publish skills. Full guide: [Plugin Catalog](/tools/clawhub). In the dashboard, the normal user surface is **Agents > select Agent > Skills**. That tab contains the skill library, plugin-catalog search/review/install, create skill, edit/configure, dependency install, and the per-Agent access toggle. A skill can be available in the library without being allowed for the selected Agent. Marketplace installs can target the shared skill library (`~/.fased/skills`) or the selected Agent workspace. The target is shown in the install review before any files are written. Use **+ Skill** in **Agent > Skills** to create a new workspace skill. The create dialog writes a real editable `SKILL.md` into the selected Agent workspace and offers starter templates for general workflows, research/review, tool/API workflows, wallet-safe workflows, operational runbooks, task automation, and channel workflows. Templates are built-in starters; create the skill, then edit its `SKILL.md` to make it specific. Bundled or plugin-owned skills stay read-only until copied into an Agent workspace. Fased also includes a bundled **skill-workshop** skill. It is review-only: it drafts a proposed `SKILL.md`, dependency list, and access review, but it must not write files, install dependencies, or grant tools/wallets by itself. Save the draft through **Agent > Skills > + Skill** or the Skill editor after review. Install targets mean: * **Shared library**: reusable skill source that Agents can allow. * **Agent workspace**: editable skill copy saved under that Agent's workspace. * **Default Agent workspace**: the current default Agent, usually `Assistant`. ## Skill sources and setup blockers Skills have a **source** and a separate **readiness state**. Do not treat those as the same thing. | Source | What it means | Where it lives | | --------------- | --------------------------------------------------------- | ------------------------------------- | | Bundled | Shipped with Fased. Read-only until copied. | `/skills/...` or the app bundle | | Shared library | Installed or created once for all Agents on this machine. | `~/.fased/skills/...` | | Agent workspace | Editable skill owned by one Agent workspace. | `/skills/...` | | Plugin catalog | Downloaded after review from the skills registry. | Shared library or an Agent workspace | | Plugin skill | Supplied by an enabled extension. | The extension's skill directory | Readiness blockers tell the operator what still needs setup: * **Needs dependency** means the `SKILL.md` exists, but a required executable is missing from the gateway `PATH`. * **Unsupported OS** means the skill declares an OS requirement such as `darwin`, and the current gateway or paired skill runtime does not match it. * **Needs config** means the skill depends on a config path or account setup. * **Needs API key/env** means the skill needs a secret value saved under `skills.entries.`. * **Ready** means the skill source is present and all declared requirements are visible to the gateway process. Example: `blogwatcher` is a bundled skill that teaches the Agent how to monitor RSS/Atom feeds, but it requires the external `blogwatcher` CLI. Clicking its install action runs only the declared dependency installer for that CLI. It does not install the skill itself, grant tools, grant wallets, or attach the skill to an Agent. If the installer uses Go and `go` is missing, Fased stops and tells you to install Go first; it does not silently install Go, Homebrew, or apt packages for you. `blogwatcher` uses Go because its own `SKILL.md` declares: `github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest`. Other skills can declare different installers, such as npm, uv, brew, or a direct download. Example: `bluebubbles` is a bundled skill that depends on the BlueBubbles channel account. Its `config:channels.bluebubbles` requirement is not skill-local JSON. The skill detail modal can edit that root config path directly, or you can use **Agent > Channels** for the fuller channel account UI. The skill becomes ready when the channel account config and credentials are present. Skill config is only for values owned by the skill itself. Homebrew on Linux is Linuxbrew. It can work on WSL, but the gateway process must see the Linuxbrew `bin` directory in `PATH`. If you run Fased from systemd, Docker, or another non-login process, install dependencies inside that runtime or explicitly set the service `PATH`. Skill dependency installs always run as the **gateway process user**. Local, Hosting/VPS, Docker, and systemd profiles can have different usernames, `HOME` directories, write permissions, and `PATH` values. Fased checks the active gateway environment after an installer runs; it does not assume `/home/fc`, `/root`, root access, or an interactive shell profile. If npm/go/uv installs a binary into that user's home or a custom prefix but the gateway cannot see it on `PATH`, the install is reported as incomplete until you update the gateway environment and restart. Dependency installers are an external package trust boundary. Before running `npm`, `go`, `uv`, `brew`, or direct download installers, **Agent > Skills** shows whether the installer is exact-version pinned and whether the source has `integrity`, `sha256`, or `shasum` metadata. Fased warns instead of silently trusting `latest`, ranges, unpinned Homebrew formulas, or archives without a hash. The install is still separate from skill access: it does not grant Agent tools, wallet access, mining access, or task autonomy. ### Create a template skill in the UI Use this path when you want to write a new skill from a starter template: 1. Open **Agents**, select the Agent, then open **Agent > Skills**. 2. Click **+ Skill**. 3. Enter a short **Name** and a practical **Description**. 4. Pick a **Template**: * **General workflow** for broad step-by-step instructions. * **Research/review** for source checking and evidence synthesis. * **Tool/API workflow** for API, CLI, or service-backed procedures. * **Wallet-safe workflow** for wallet-aware planning with explicit grant checks. * **Operational runbook** for triage, remediation, and escalation. * **Task automation** for scheduled or worker-backed task workflows. * **Channel workflow** for Telegram, Discord, Slack, or other app behavior. 5. Pick **Save in Agent**. Use `Assistant` for the default Agent, or another Agent name when the skill should be owned by that Agent. 6. Click **Create skill**. Fased writes a real editable `SKILL.md`. 7. Open the new skill from **Agent > Skills** and edit `SKILL.md`. 8. Allow the skill on the Agent from the skill detail **Agent access** section or from the row toggle. The template is only starter text. It does not grant tools, service credentials, wallet access, mining access, or task autonomy. Configure those separately in **Services**, **Agent > Tools**, **Wallets > Skill Grants**, and **Agent > Skills**. Status words in the UI are intentionally separate: * **Installed** means Fased found a skill folder with `SKILL.md`. * **Ready** means the skill is installed and all required binaries, env values, config values, and OS requirements are visible to the gateway process. * **Needs dependency** means the skill exists, but an external binary such as `gh`, `op`, or `eightctl` is missing from the gateway `PATH`. In WSL, install the binary inside WSL or expose it to the process that runs Fased. * **Unsupported OS** means the skill is for another platform, such as a macOS skill on a Linux/WSL gateway. Pair a matching node or use a cross-platform alternative. * **Configure** saves skill-specific config or env values. It does not install binaries and does not grant tools or wallets. * **Make editable copy** copies a read-only bundled/shared skill into the selected Agent workspace so its `SKILL.md` can be edited. It is not a security grant and it does not change which Agents may use the skill. **Agent > Skills** has three access modes for the selected Agent: * **Inherits all**: no per-Agent allowlist; the Agent can use every enabled skill. * **Explicit allowlist**: the Agent can use only the selected skills. * **No skills**: the Agent receives no skill instructions or skill tools. Normal user flow: 1. Open **Agents**, select the Agent, then open **Agent > Skills**. 2. Search the plugin catalog or use an existing bundled/workspace/shared skill. 3. Review install/download safety, then install into the shared library or the selected Agent workspace. 4. To edit a bundled, plugin-owned, or extra-folder skill, copy it into the Agent workspace first. The editor only writes managed/shared skills and workspace copies. 5. Fix setup blockers in the skill detail modal: API key, binary dependency, config requirement, or enable/disable state. 6. Attach the skill to the Agent that should use it. You can do this from the skill detail modal's **Agent access** section or the row toggle. 7. If the skill calls tools, open **Agent > Tools** and allow the required tools. If it needs API credentials, connect the API in **Services**. If it can move funds, open the **Wallets > Skill Grants** tab and grant only the narrow wallet actions. 8. Use the skill in chat or tasks. Tasks inherit the owning Agent's skill allowlist unless the task explicitly narrows its selected skills. Common flows: * Install a skill into your Fased workspace: * `fased skills marketplace install ` * Preview an update: * `fased skills marketplace update --dry-run` * Apply a reviewed risky update: * `fased skills marketplace update --approve-permission-change` * Sync (scan + publish updates): * `clawhub sync --all` Fased marketplace install/update records the plugin source, archive scan, requested permissions, and update review in `/skills//.clawhub/origin.json`. Use the raw catalog CLI directly for discovery and publishing workflows. ## Wallet-capable skills Installed or custom skills do not receive wallet access automatically. The operator must grant the exact wallet actions, route mints, registry origin, and automation scope that the skill may use. In the dashboard, use the **Wallets > Skill Grants** tab to review wallet-capable skills and grant only the actions, chain, mint route, amount cap, slippage cap, and automation flags you intend to allow. The UI shows the wallet permissions recorded during plugin install review next to the current grant and writes the same `skills.entries..config.walletActions` path as the CLI. The list is intentionally empty until a plugin review records wallet permissions or an existing wallet grant is present. Use the CLI helper when you need scriptable setup or a raw admin path: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fased skills wallet grant reviewed-wallet-skill \ --registry https://clawhub.com \ --actions send \ --role agent \ --wallet-id agent \ --chain solana \ --input-mint So11111111111111111111111111111111111111112 \ --output-mint \ --max-amount 100000000 \ --max-slippage-bps 50 \ --autonomous \ --cron ``` This writes `skills.entries.reviewed-wallet-skill.config.walletActions` and, when `--registry` is provided, adds the registry to `skills.marketplace.allowRegistries`. Wallet grants are always explicit Agent-wallet grants. A skill must be granted the specific Agent wallet ids it may use, such as `agent` or `agent-2`. Skills cannot use Mining wallets or Vault wallets for generic wallet actions. Installed plugin-catalog skills are also checked against `/skills//.clawhub/origin.json`; wallet actions are rejected unless the recorded registry is allowlisted. Mining is a separate runtime surface. Mining skills may teach the Agent how to read mining status or call mining tools when those tools are explicitly allowed, but generic marketplace skills do not gain custody over the mining wallet. SAT mining wallet actions stay behind the mining tool policy, runtime approvals, and the dedicated mining wallet path. Plugin-catalog installs record the wallet permissions, requested tool access, and install metadata requested by the skill. Updates that add or change risky wallet permissions, tool access, install metadata, or new archive scan warnings are blocked until explicitly approved. Fased also scans plugin archives before install and rejects hidden package scripts, installer scripts, sensitive files, native binary artifacts, dangerous source-code patterns, dependency blocks, symlinks, VCS folders, `node_modules`, and oversized files. Dependency manifests and helper scripts are recorded as review warnings. To review installed plugin sources, requested permissions, archive scan status, and current grants: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fased skills marketplace list fased skills permissions reviewed-wallet-skill ``` For review-only setup, use: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fased skills wallet grant reviewed-wallet-skill --actions send --dry-run --json ``` ## Security notes * Treat third-party skills as **untrusted code**. Read them before allowing them on an Agent. * Dependency installers are blocked when the local scanner finds critical dangerous-code patterns in the skill source. Review or remove the skill instead of installing dependencies blindly. * Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing). * `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process for that agent turn (not the sandbox). Keep secrets out of prompts and logs. * Use **Wallets > Skill Grants** for wallet-capable skills so wallet routes, token mints, registry origins, and autonomous permissions stay explicit. `fased skills wallet grant` is the scriptable equivalent. * For a broader threat model and checklists, see [Security](/gateway/security). ## Format (AgentSkills-compatible) `SKILL.md` must include at least: ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} --- name: nano-banana-pro description: Generate or edit images via Gemini 3 Pro Image --- ``` Notes: * We follow the AgentSkills spec for layout/intent. * The parser used by the embedded agent supports **single-line** frontmatter keys only. * `metadata` should be a **single-line JSON object**. * Use `{baseDir}` in instructions to reference the skill folder path. * Optional frontmatter keys: * `homepage` — URL surfaced as “Website” in the skill detail UI (also supported via `metadata.fased.homepage`). * `user-invocable` — `true|false` (default: `true`). When `true`, the skill is exposed as a user slash command. * `disable-model-invocation` — `true|false` (default: `false`). When `true`, the skill is excluded from the model prompt but still available via user invocation. * `command-dispatch` — `tool` (optional). When set to `tool`, the slash command bypasses the model and dispatches directly to a tool. * `command-tool` — tool name to invoke when `command-dispatch: tool` is set. * `command-arg-mode` — `raw` (default). For tool dispatch, forwards the raw args string to the tool (no core parsing). The tool is invoked with params: `{ command: "", commandName: "", skillName: "" }`. ## Gating (load-time filters) Fased **filters skills at load time** using `metadata` (single-line JSON): ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} --- name: nano-banana-pro description: Generate or edit images via Gemini 3 Pro Image metadata: { "fased": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] }, "primaryEnv": "GEMINI_API_KEY", }, } --- ``` Fields under `metadata.fased`: * `always: true` — always include the skill (skip other gates). * `emoji` — optional emoji used by the skill detail UI. * `homepage` — optional URL shown as “Website” in the skill detail UI. * `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes. * `requires.bins` — list; each must exist on `PATH`. * `requires.anyBins` — list; at least one must exist on `PATH`. * `requires.env` — list; env var must exist **or** be provided in config. * `requires.config` — list of `fased.json` paths that must be truthy. * `primaryEnv` — env var name associated with `skills.entries..apiKey`. * `install` — optional array of installer specs used by Agent > Skills dependency install (brew/node/go/uv/download). Note on sandboxing: * `requires.bins` is checked on the **host** at skill load time. * If an agent is sandboxed, the binary must also exist **inside the container**. Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image). `setupCommand` runs once after the container is created. Package installs also require network egress, a writable root FS, and a root user in the sandbox. Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI in the sandbox container to run there. Installer example: ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} --- name: gemini description: Use Gemini CLI for coding assistance and Google search lookups. metadata: { "fased": { "emoji": "♊️", "requires": { "bins": ["gemini"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "gemini-cli", "bins": ["gemini"], "label": "Install Gemini CLI (brew)", }, ], }, } --- ``` Notes: * If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node). * If all installers are `download`, Fased lists each entry so you can see the available artifacts. * Installer specs can include `os: ["darwin"|"linux"|"win32"]` to filter options by platform. * Node installs honor `skills.install.nodeManager` in `fased.json` (default: npm; options: npm/pnpm/yarn/bun). This only affects **skill installs**; the Gateway runtime should still be Node (Bun is not recommended for WhatsApp/Telegram). * Prefer exact installer pins: `package@1.2.3` for npm, `module@v1.2.3` for Go, and `package==1.2.3` for uv. Homebrew formulas are treated as unpinned package manager installs unless paired with separate trust metadata. * Installer specs can include `integrity`, `sha256`, or `shasum` so the UI and review surfaces can warn less aggressively and detect missing source pins. * Go and uv installs require `go` or `uv` to already be available to the gateway process. Fased does not silently install toolchain managers. * Installer success requires verification. When a spec declares `bins`, Fased re-checks those binaries after the command exits. Exit code `0` is not enough: if the binary is still missing from gateway `PATH`, the install is reported as failed with a PATH hint. * Download installs: * `url` (required) * `archive` (`tar.gz` | `tar.bz2` | `zip`) * `extract` (default: auto when archive detected) * `stripComponents` * `targetDir` (default: `~/.fased/tools/`) If no `metadata.fased` is present, the skill is always eligible (unless disabled in config or blocked by `skills.allowBundled` for bundled skills). ## Config overrides (`~/.fased/fased.json`) Bundled/managed skills can be toggled and supplied with env values: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { skills: { entries: { "nano-banana-pro": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE", }, config: { endpoint: "https://example.invalid", model: "nano-pro", }, }, peekaboo: { enabled: true }, sag: { enabled: false }, }, }, } ``` Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys). Config keys match the **skill name** by default. If a skill defines `metadata.fased.skillKey`, use that key under `skills.entries`. Rules: * `enabled: false` disables the skill even if it’s bundled/installed. * `env`: injected **only if** the variable isn’t already set in the process. * `apiKey`: convenience for skills that declare `metadata.fased.primaryEnv`. Supports plaintext string or SecretRef object (`{ source, provider, id }`). * `config`: optional bag for custom per-skill fields; custom keys must live here. * `allowBundled`: optional allowlist for **bundled** skills only. If set, only bundled skills in the list are eligible (managed/workspace skills unaffected). ## Environment injection (per agent run) When an agent run starts, Fased: 1. Reads skill metadata. 2. Applies any `skills.entries..env` or `skills.entries..apiKey` to `process.env`. 3. Builds the system prompt with **eligible** skills. 4. Restores the original environment after the run ends. This is **scoped to the agent run**, not a global shell environment. ## Session snapshot (performance) Fased snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session. Skills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears. Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn. ## Remote macOS nodes (Linux gateway) If the Gateway is running on Linux but a **macOS node** is connected with `system.run` allowed, Fased can treat macOS-only skills as eligible when the required binaries are present on that node. This requires Exec approvals security to be something other than `deny`. The agent should execute those skills through the `nodes` tool, usually `nodes.run`. This relies on the node reporting its command support and on a bin probe through `system.run`. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects. ## Skills watcher (auto-refresh) By default, Fased watches skill folders and bumps the skills snapshot when `SKILL.md` files change. Configure this under `skills.load`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { skills: { load: { watch: true, watchDebounceMs: 250, }, }, } ``` ## Token impact (skills list) When skills are eligible, Fased injects a compact XML list of available skills into the system prompt through the embedded agent prompt formatter. The cost is deterministic: * **Base overhead (only when ≥1 skill):** 195 characters. * **Per skill:** 97 characters + the length of the XML-escaped ``, ``, and `` values. Formula (characters): ``` total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped)) ``` Notes: * XML escaping expands `& < > " '` into entities (`&`, `<`, etc.), increasing length. * Token counts vary by model tokenizer. A rough OpenAI-style estimate is \~4 chars/token, so **97 chars is about 24 tokens** per skill plus your actual field lengths. ## Managed skills lifecycle Fased ships a baseline set of skills as **bundled skills** as part of the install or macOS app bundle. `~/.fased/skills` exists for local overrides (for example, pinning/patching a skill without changing the bundled copy). Workspace skills are user-owned and override both on name conflicts. ## Config reference See [Skills config](/tools/skills-config) for the full configuration schema. ## Looking for more skills? Open **Agent > Skills** and use the plugin catalog search. ***