flexkit skills

Manages the project’s skills: Markdown how-to documents the agent loads when a task matches their description. You can create and edit Studio skills one at a time, or pull them into a folder of Markdown files and push changes back, so a team can review skills in pull requests like any other code.

Synopsis

flexkit skills <subcommand> [arguments] [options]

Running flexkit skills without a subcommand runs flexkit skills ls. Wherever a command takes <idOrName>, you can pass the skill id or its exact name (case-insensitive).

Where skills come from

Every skill has a source, shown in the SOURCE column of flexkit skills ls:

Skills from code and plugins are read-only here: update and rm refuse them, and push skips them. To change one, run flexkit skills fork to get an editable personal copy. See define skills in code for code skills.

skills ls

List the skills you can use. Personal skills of other members and skills of spaces you are not in are not listed.

flexkit skills ls [--search <text>] [--visibility <list>] [--limit <n>] [--offset <n>] [--json]

Examples

# List skills, most recently updated first
flexkit skills ls
 
# Rank skills by relevance to a task, as the agent does
flexkit skills ls --search "refund an order"
 
# Only your personal skills, names only
flexkit skills ls --visibility personal --json | jq -r '.skills[].name'
 
# Second page of 100
flexkit skills ls --limit 100 --offset 100

skills inspect

Show a skill’s metadata followed by its Markdown content. Alias: get.

flexkit skills inspect <idOrName> [--content] [--json]

Examples

# Show a skill by name
flexkit skills inspect refund-policy
 
# Save only the content to a file
flexkit skills inspect refund-policy --content > refund-policy.md
 
# Read one field
flexkit skills inspect 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --json | jq -r '.skill.description'

skills add

Create a Studio skill from a Markdown file, or from stdin with -. If the file starts with front matter, its name, description, visibility and space are used; flags override them. The name defaults to the file name without .md. A description is required: the agent reads it to decide when to load the skill. Alias: create.

flexkit skills add <file|-> [--name <name>] [--description <text>] [--visibility <visibility>] [--space <spaceId>] [--json]

Examples

# Create a skill from a file
flexkit skills add ./refunds.md --name refund-policy --description "How to approve and issue refunds"
 
# Use the name and description in the file's front matter
flexkit skills add ./skills/onboarding-checklist.md
 
# Create a personal skill from stdin
cat notes.md | flexkit skills add - --name my-shortcuts --description "My reporting shortcuts" --visibility personal
 
# Share a skill with one space only
flexkit skills add ./sales-playbook.md --description "Sales follow-up steps" --space 7d1e0b52-3c44-4f0e-a2b1-9f8e7d6c5b4a

skills update

Change a Studio skill. Fields you do not pass keep their current value. With --file, the file’s content replaces the skill’s content, and its front matter name and description apply too unless you pass the flags.

flexkit skills update <idOrName> [--file <file|->] [--name <name>] [--description <text>] [--visibility <visibility>] [--space <spaceId>] [--json]

Examples

# Replace the content from a file
flexkit skills update refund-policy --file ./refunds.md
 
# Rename a skill
flexkit skills update 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --name refund-policy-eu
 
# Make a personal skill available to the whole project
flexkit skills update my-shortcuts --visibility project

skills rm

Delete a Studio skill. Automations that attached it no longer load it. The command asks for confirmation; pass --yes in scripts. Alias: remove.

flexkit skills rm <idOrName> [--yes] [--json]

Examples

# Delete a skill
flexkit skills rm refund-policy
 
# Delete without a prompt
flexkit skills rm 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --yes

skills fork

Copy any skill you can see, including skills from code and plugins, into a new personal Studio skill named <name> (copy). Rename it or change its visibility with flexkit skills update.

flexkit skills fork <idOrName> [--json]

Examples

# Fork a plugin skill to adapt it
flexkit skills fork shopify/order-lookup
 
# Fork and keep the new id for the next command
id=$(flexkit skills fork catalog-review --json | jq -r '.skill.id')
flexkit skills update "$id" --name catalog-review-strict --visibility project

skills pull

Write every Studio skill you can see as a Markdown file into a folder (default ./skills). A file that already holds a skill’s id is overwritten in place, so renamed skills do not leave stale copies; a file without an id whose name matches is reused too. New skills get <slug-of-name>.md. Files of skills that no longer exist are left alone. Skills from code and plugins are not pulled.

flexkit skills pull [dir] [--dry-run] [--json]

Examples

# Pull into ./skills
flexkit skills pull
 
# Pull into another folder
flexkit skills pull ./docs/agent-skills
 
# See which files would change
flexkit skills pull --dry-run

skills push

Create or update Studio skills from the Markdown files in a folder (default ./skills). For each file:

• A file matches a skill by its id front matter, else by name (case-insensitive). Without a name, the file name is the name.
• No match: the skill is created. Matches with a difference in name, description, content, visibility or space: it is updated. Otherwise it is left unchanged.
• A file that matches a skill from code or a plugin is skipped: code skills are managed by flexkit dev and flexkit tools sync, plugin skills by their plugin.
• Files that would fail validation (missing description, over the limits, two files with one name) are reported as invalid and not sent.

Studio skills that no file matches are kept. Pass --prune to delete them; the command asks first unless you pass --yes, and deletes nothing while any file is invalid. Run --dry-run to see the plan without changing anything. The command exits with code 1 when a file is invalid or a request fails.

flexkit skills push [dir] [--dry-run] [--prune] [--yes] [--json]

Examples

# Preview what would change
flexkit skills push --dry-run
 
# Push ./skills
flexkit skills push
 
# Make the project match the folder exactly, in CI
flexkit skills push ./skills --prune --yes
 
# List the planned creates as JSON
flexkit skills push --dry-run --json | jq '.actions[] | select(.type == "create") | .file'

File format

pull writes, and add, update --file and push read, Markdown with YAML front matter:

---
id: 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f
name: refund-policy
description: 'Use when a customer asks for a refund: checks eligibility and issues it'
visibility: project
---
 
# Refunds
 
1. Find the order by number or customer email.
2. Refund only orders delivered in the last 30 days.
3. Report the refund id back to the user.

The content after the front matter is limited to 50,000 characters. Plain, quoted and | / > block values are supported; other YAML (lists, nested objects) is not.

Options

See also the global options.

Permissions

• Listing and reading skills needs the Owner, Developer or Viewer role.
• Creating, changing, forking and deleting skills needs the Owner or Developer role.
• Commands work with a flexkit login session and with project API tokens. A token acts as the member who created it, so it sees that member’s personal skills and the skills of its spaces.

Keep skills in git

# Once: pull the current skills and commit them
flexkit skills pull ./skills
git add skills && git commit -m "Add agent skills"
 
# In a pull request: show what merging would change
flexkit skills push ./skills --dry-run
 
# After merge, in CI with a project API token
FLEXKIT_TOKEN=$FLEXKIT_TOKEN flexkit skills push ./skills --project my-project-id --yes

Skills edited in Studio after the pull are overwritten by the next push from an older file. Pull before you edit, or treat the folder as the source of truth and add --prune so the project mirrors it.