Finetuning Skill

The Finetuning skill teaches AI coding agents how to drive the ft CLI end-to-end. Ask Claude Code (or Cursor, Codex, Aider, Cline, Windsurf, etc.) something like "make me a 30-second lofi piano track" and the skill walks the agent through the right commands: confirm ft is installed, confirm you're logged in, then generate, list, or download.

It ships in two interchangeable formats:

• SKILL.md — the Claude Code skill (with frontmatter Claude Code reads at trigger time).
• AGENTS.md — the same content with no Claude-specific markers, for any other agent that picks up AGENTS.md files automatically.

What the skill does

• Detects state up front. Silently runs ft --version and ft auth whoami before doing anything. If ft isn't installed, it gives the right one-liner for the OS. If you're not logged in, it walks you through minting a key and running ft auth login.
• Drives the happy paths. Generate (ft generate), list (ft list), inspect (ft get), download (ft download), check credits (ft me), manage playlists (ft playlists, ft playlist add/remove/move), and delete tracks (ft delete).
• Handles errors gracefully. Surfaces the right next step on 401 / 402 / 403 / 429 / QUEUE_FULL, and explains the playlist privacy rule (the API can't make a private track public — the web app can).
• Avoids common traps. Won't pass --json to ft generate and silently skip the download. Won't pass short IDs where the API expects full UUIDs. Won't suggest re-submitting after a Ctrl-C (which burns a credit). Won't pass --yes to ft delete without your explicit confirmation — deletion is permanent.

Prerequisites

• An AI coding agent — Claude Code (CLI, desktop, or web), Cursor, Codex, Aider, Cline, Windsurf, or anything else that loads project context.
• A Finetuning.ai account on the Pro or Lifetime plan — the public API is paid-only.
• The ft CLI itself. The skill will help you install it if it's missing, or grab it ahead of time.

Install for Claude Code

Option A — Clone into ~/.claude/skills/

git clone https://github.com/Nattothemoon/finetuning-cli-skill.git \
  ~/.claude/skills/finetuning-cli

Restart Claude Code (or open a new session) and the skill becomes available.

Option B — Packaged .skill file

Download finetuning-cli-skill.skill from the Releases page and install via Claude Code's skill manager (or extract its contents into ~/.claude/skills/finetuning-cli/).

Try it

Start a new Claude Code session and try one of these:

• make me a 60 second chill lofi piano track for studying
• list my last 10 generations on finetuning
• add my last three tracks to my Focus Beats playlist
• how many credits do I have left this month?
• I'm on a fresh Windows laptop — help me set up finetuning from terminal

Claude will load the skill, run the install/login pre-check silently, then proceed to the actual task.

Install for other AI agents

If your agent of choice isn't Claude Code, use AGENTS.md — same content, no Claude-specific frontmatter. Drop it into the root of any project where you want the agent to know how to drive ft:

curl -fsSL https://raw.githubusercontent.com/Nattothemoon/finetuning-cli-skill/main/AGENTS.md > AGENTS.md

Most agents (Codex, Cursor, Aider, Cline, Windsurf, ...) pick up AGENTS.md automatically. For others you may need to point them at the file explicitly.

How the skill thinks

Internally the skill always runs this decision tree first, silently:

1. Is ft installed? Runs ft --version. If missing, jumps to the install section and gives the right one-liner for your OS.
2. Are you logged in? Runs ft auth whoami. If 401 or "no API key found", walks you through ft auth login.
3. Otherwise, you're ready. The agent goes straight to the command you actually asked for.

The check is silent unless something fails — if everything passes, the agent skips straight to the work.

The order matters: install is the most expensive recovery (download + PATH), login is medium (one paste), and the actual command is what you came for. Checking everything up front avoids the agent surprising you with "wait, you also need to log in" mid-task.

Updating the skill

• Cloned into ~/.claude/skills/finetuning-cli/: cd ~/.claude/skills/finetuning-cli && git pull, then restart Claude Code.
• Installed via .skill file: download the latest from Releases and re-install.
• Using AGENTS.md in your project: re-curl the URL above to overwrite your local copy.

Claude Code does not auto-update skills, so this is always a manual pull.

Source

The skill is open source (MIT) at Nattothemoon/finetuning-cli-skill. Issues and PRs welcome.

What's next