Just want to install the skill? See Agent skill. This page has the per-agent detail.

​
In a project, nothing extra

A project made with npm create vfrey@beta my-channel already contains everything an agent needs: AGENTS.md, CLAUDE.md, GEMINI.md, and the vfrey skill for every agent (.claude/skills/vfrey/ and .agents/skills/vfrey/). Open the folder in your agent and ask for a video. There is no install step, and the skill always matches the project’s package version. CLAUDE.md and GEMINI.md only say @AGENTS.md, so every agent reads the same short text: what the folder is, the four commands an agent needs (open, tick, videos, doctor), and where things go. A project must be trusted for Grok and some other agents to load its skills and rules. See Projects.

​
Working outside a project

The rest of this page is for working outside a project, where no skill folder comes with the folder you are in. npx @vfrey/vfrey@beta skill install writes the skill into your agent’s own skills folder on your machine. It writes to Claude Code’s folder by default. Add --agent to pick another agent, or --agent all to install for all five at once. Add --project to install into the current folder’s skills folder instead of your home folder. Every row below was checked against the agent’s own docs. If you are about to work in the same place for a while, start a project instead: npm create vfrey@beta my-channel. Run each command from a folder where vfrey is installed, or use vfrey without npx if you installed it globally. See Setup.
1

Install the skill

This copies the skill to ~/.claude/skills/vfrey/, for you in every folder. It then prints “Restart Claude Code, then ask it for a video.”
2

Start a new session

Claude Code loads skills when a session starts. Quit and start claude again.
3

Ask for a video

Say: “Make me a short video about how octopuses have three hearts.”
To update after you install a newer package, run the same install command again. The old copy is moved aside, and the install prints where. Then start a new session. To remove it, run npx @vfrey/vfrey@beta skill uninstall.

​
Any other agent

Use the first step that your agent supports.
1

If your agent loads SKILL.md folders

Find its skills folder in its docs and install there. --dir writes into PATH/vfrey, so pass the skills folder, not the vfrey folder:
Many agents read ~/.agents/skills/. --dir does not combine with --agent. It prints “Restart or reload your agent, then ask it for a video.” Remove it with npx @vfrey/vfrey@beta skill uninstall --dir /path/to/its/skills.
2

If it only reads AGENTS.md

Append the skill text to the AGENTS.md in the folder where you work. The skill ships in the package, so run this from the folder where you installed vfrey:
This skips the frontmatter. With a global install, the file is at $(npm root -g)/@vfrey/vfrey/skills/vfrey-product/SKILL.md. The skill points to its push/ and examples/ folders. Those stay in the package, so tell the agent to read them from there when it needs them.
3

If it can read a URL

Tell it: “Read https://vfrey.ai/docs/llms.txt, then make me a short video about octopuses.” It can read this page as plain text too: https://vfrey.ai/docs/guides/agents.md. Then it runs the CLI directly.
The short sequence an agent runs, from the project folder:
  1. doctor checks the machine. Each failed check prints a Fix: line.
  2. tick --script-template prints an example script.json. The agent writes its own to script.json.
  3. tick --now --about "SUBJECT" --script script.json makes the video. It prints the MP4 path, the transcript path, and the upload result.
  4. open opens this project’s dashboard, starting it if needed, and prints the URL. npx vfrey videos lists the finished videos and their paths.

​
Check with doctor

npx vfrey doctor has a skill: check. It looks in the skills folder of every agent above (Claude Code, Codex, Grok, Cursor, Gemini CLI). It passes when any copy is current, and it lists each copy it found. If your copy is older than the package, the check fails and its Fix: line names the command to run, for example npx @vfrey/vfrey@beta skill install --agent codex. If none is found, the Fix: line is npx @vfrey/vfrey@beta skill install --agent <your agent>.

​
Install commands

Install writes vfrey/SKILL.md, the push/ and examples/ folders, and a .vfrey-skill.json stamp. If you run it again after a package update, it moves the old copy to vfrey.bak-DATE, renames its SKILL.md to SKILL.md.old so the agent never loads two, and prints the path.

​
When a different copy exists

If another skill named vfrey is already there, install stops with A different vfrey skill is already at PATH and a Fix: line. Pick one fix.
  • Run it again with --force to replace that copy.
  • Install somewhere else and leave the other copy alone: use --dir PATH with a different folder.

​
What the skill does

The agent follows it in this order. This is the same for every agent.
1

Check

npx vfrey doctor.
2

Make a video

npx vfrey tick --now --about "SUBJECT" with the subject you named. The agent writes the script and passes it with --script. See Agent-written scripts. With no subject, it runs npx vfrey tick --now, and the default series reads the Federal Reserve press feed. The agent does not set a dry run, because a dry run skips the real file.
3

Find the files

In a project, videos/YYYY-MM-DD TITLE.mp4 and .txt, listed by npx vfrey videos. On the machine desk, $VFREY_HOME/renders/JOB_ID.mp4 and JOB_ID.txt. The default home is ~/.vfrey.
4

Say what happened to publish

A new series is not live, so the summary says Not uploaded to youtube: this series is not live yet (and Dry run (--dry-run) only for the flag, Upload skipped: no key for youtube once the series is live without a key), plus “Replies skipped: no platform keys”. The agent says the video stays on your machine until the series is live and has a key. It does not promise a push, because npx vfrey push refuses for now.
5

Open the dashboard, if you want to look

npx vfrey open. It reuses this project’s dashboard or starts one, and prints the URL. See Local desk.

​
Agent-written scripts

When an agent drives, it should write the script itself. Without --script, vfrey writes a basic script on its own. That script is a placeholder unless a model is configured.
script.json has four fields: The subject is the --about text. Without --about, it is the script’s subject field, or else its title. The skill passes --about and leaves subject out; npx vfrey tick --script-template prints an example that includes it. The lines must use at least 2 of the subject’s key words, or the script is rejected for subject-binding. A bad file is refused with a line that names the field and a Fix: line. More than 8 lines are folded into 8 visual beats, and the voice still reads every line. Six to ten short lines is best. Say only what is true, with no invented numbers or quotes. An example, for the subject “why honey never spoils”:
Keep the file inside these limits.

​
A length you were asked for

When the person asks for a length, such as “20 to 30 seconds”, the agent passes it: npx vfrey tick --now --about "SUBJECT" --script script.json --duration 20-30. A range is in seconds, and one number means that target with 15% either side. The film is the voice plus 0.3 s, and the voice speaks about 2.6 words a second, so 20 to 30 seconds is about 52 to 78 words. After the voice is made and before the render, vfrey checks the length. A film outside the range stops with duration_range, how far off it is, and a Fix: that says how many words to cut or add. Write the script again and rerun. Without --duration, the length is whatever the script takes to say.
A --script run is a one-off video. A series job in progress does not block it.

​
Agent-written scenes

The agent also designs the picture. It runs npx vfrey scene init DIR, edits the scene, looks at a frame with render --scene DIR --engine ENGINE_ID --script script.json --frame 2.5 out.png, then passes --scene DIR --engine ENGINE_ID to tick. Until a voice exists, a frame is timed by an estimate from the script; after the first full render the same command uses the real voice, so the agent looks at the frames at the beat times again, because they can differ. See Scenes.

​
What an agent does not do

  • It does not scrape, drive a browser, or download other creators’ videos.
  • It does not post without the AI-disclosure flag.
  • There is no MCP server. The skill, or this page, is how the agent finds the commands.