> ## Documentation Index
> Fetch the complete documentation index at: https://fal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Discover, install, edit, and activate skills for fal Agent conversations.

Skills provide instructions and reference files for a task. The agent can select enabled skills automatically.
Use `fal.skills` when you want to activate a specific skill.

## Discover and activate a skill

```ts theme={null}
import { agent } from "./client.ts";

const skills = await agent.skills.list({ search: "product" });
const skill = skills.find((item) => !item.disabled && !item.shadowed);
if (skill) {
  const response = await agent.run({
    input: "Plan product photos for a blue ceramic mug.",
    fal: { skills: [skill.name] },
  });
  console.log(response.output_text);
}
```

Use skill names for activation and skill IDs for management.
A request accepts up to 50 skill names, each containing 1–100 characters.
Activation persists in the conversation. Later turns inherit activated skills.
An empty array does not clear existing activations.
Unavailable or disabled names are ignored. The account's master skills switch still applies.

`skills.list` accepts optional `search` and `conversationId` fields.
Results include fal skills and installed user skills, with `disabled` and `shadowed` flags.
A fal skill can shadow a user skill with the same name.
Use `skills.retrieve(id)` to read one visible skill, including its body and reference files.

## Import from GitHub

```ts theme={null}
import { agent } from "./client.ts";

const source = {
  repoUrl: "https://github.com/YOUR_ORG/YOUR_SKILLS",
  subpath: "skills/product-photos",
};
const preview = await agent.skills.previewImport(source);
console.log(preview.warnings);
```

The source accepts an optional Git ref and a subdirectory path.
Private repositories are not supported.
The preview reports the resolved commit, file counts, name conflicts, and unsupported scripts.
Previewing does not install the skill. Review the contents and warnings before installation.

```ts theme={null}
import { agent } from "./client.ts";

const skill = await agent.skills.importFromGithub({
  repoUrl: "https://github.com/YOUR_ORG/YOUR_SKILLS",
  ref: "REVIEWED_COMMIT_SHA",
  subpath: "skills/product-photos",
});
console.log(skill.id);
```

Scripts are not supported for installation. A conflicting user skill name blocks installation.
Importing the same repository and path updates the existing installation.
A conflicting fal skill produces a shadowing warning instead.

## Create and edit

```ts theme={null}
import { agent } from "./client.ts";

const { skill } = await agent.skills.create({
  name: "product-photos",
  description: "Plan consistent product photography.",
  body: "Use soft studio light. Keep the product color unchanged.",
});
console.log(skill.id);
```

Use `skills.save(id, content)` to replace a user skill's name, description, body, and references.
Names contain 1–64 lowercase letters, digits, or hyphens, without a leading or trailing hyphen.
Descriptions contain 1–1,024 characters. The body must not be empty.
Reference paths must identify text files under `references/`.
Saving an imported skill detaches it from GitHub. Repository updates are then unavailable for that skill.
You cannot edit or uninstall fal-provided skills through these methods.

## Enable, update, or uninstall

```ts theme={null}
import { agent } from "./client.ts";

const skill = await agent.skills.retrieve("SKILL_ID");
await agent.skills.setEnabled({
  origin: skill.origin,
  key: skill.id,
  enabled: true,
});
```

Disabling a skill preserves its installation. Uninstalling removes an owned user skill.
Use `skills.checkForUpdates(id)` for GitHub installations.
The result contains `currentSha`, `latestSha`, and `hasUpdate`.
Call `skills.update(id)` to fetch and apply the repository update.

Skill writes are sent once. After an uncertain network result, read the skill before repeating a mutation.
See the [method reference](/docs/documentation/agent/sdk/methods#skills) for every method and its return type.