Write your own s1ft skill

A skill is a single SKILL.md file that tells an AI agent how to do one job with your meeting data, for example a weekly client digest or a one-page brief before a call. This page shows the file format, how to get meeting data, how to test the skill on your Mac, and two ways to share it.

If you only want to install or change a library skill, see Connect AI agents. To see the skills that exist today, open the s1ft skills page.

What you need

S1ft 1.3 or later, with at least one recorded meeting. See Getting Started with s1ft.
An agent that reads Agent Skills: Claude Code, Codex, Cursor, Gemini CLI, or Claude Desktop.
The base skill s1ft installed. The install steps are on the Connect AI agents page.

The SKILL.md format

Each skill is one folder with one file: skills/<name>/SKILL.md. The file has a frontmatter block between two --- lines, then Markdown instructions for the agent.

---
name: client-digest
description: Use when the user wants a short digest of their client calls from the last week. Reads the transcript and the meeting details.
compatibility: Needs the s1ft skill and the s1ft macOS app (S1ft.app) with at least one recorded meeting.
allowed-tools: Bash(s1ft:*) Read
metadata:
  s1ft-uses: "transcript,meeting"
---

# Client digest

## 1. Get the data

Use the `s1ft` skill for data access. Do not repeat its setup here.

## 2. Write the digest

...

The frontmatter allows only these top-level keys:

Key	What it holds
`name`	The skill name. It must equal the folder name.
`description`	When the agent should use the skill. Required, not empty.
`license`	Optional. The license of your skill.
`compatibility`	Optional. What the skill needs to run.
`allowed-tools`	Optional. The tools the skill may call, for example `Bash(s1ft:*) Read`.
`metadata`	Optional in general, but a skill that reads s1ft data sets the key `s1ft-uses` here.

Say which data the skill reads: metadata.s1ft-uses

The key metadata.s1ft-uses is a comma separated string. It lists the kinds of meeting data your skill reads. It accepts these values:

transcript: the words that were said (transcript.json).
meeting: the title, time, platform and attendees (meeting.json).
voice: the numbers about your own voice (telemetry.json).

For example, s1ft-uses: "transcript,meeting" means the skill reads the transcript and the meeting details, and nothing about your voice. List only what the skill needs. Anyone who reads the file can then see what data it touches.

Write the description as a trigger: start with “Use when…”, then say what the skill does and which data it reads. The agent picks a skill by this sentence.

Get the data through the base skill

Tell the agent to get meeting data through the base skill s1ft. Don’t read the data files of another skill’s folder, and don’t write your own folder scanning. The base skill already handles the setup of the command line, the version check, an empty result, and a missing meetings folder.

In your skill, write a short “Get the data” section that names the commands you need:

s1ft meetings list --since <date> --until <date> --json finds meetings in a period.
s1ft meetings search <text> finds meetings by name or transcript text.
s1ft meetings show <id> --json gives the meeting details and the transcript.
s1ft voice stats <id> --json gives numbers about your voice, if your skill lists voice in s1ft-uses.

For a period, read one meeting at a time and keep only the results. This stops the agent from filling its context with transcripts.

For the full list of options, defaults and exit codes, see the command line reference. For the fields in meeting.json, transcript.json and telemetry.json, see Meeting data files.

Test the skill on your Mac

Test before you publish. A test uses your real meetings, so it stays on your Mac.

Make a folder named <name> in your agent’s skills folder and put your SKILL.md in it. The folder name must equal name in the frontmatter. If you are not sure where your agent keeps its skills, see its documentation.
Start a new agent session so the agent picks up the skill.
Ask for the job in plain words, in the way your description says. For example: “Make a digest of my client calls from last week.”
Check the answer against the meeting. Open the meeting’s transcript.json and compare the quotes and times.
Try the edge cases: a period with no meetings, a meeting with no transcript, and a meeting recorded before S1ft 1.3.
Change the SKILL.md, start a new session, and run it again until the result is right.

If the agent doesn’t use your skill, make the description more specific about when to use it.

Publish a skill in your own repo

You can share a skill without asking anyone. Put it in a public GitHub repo.

Create a repo, for example your-name/s1ft-client-digest.
Keep the same layout: skills/<name>/SKILL.md.
Add a README with one sentence about what the skill does and the install command.
Others install it with the same skills command as the library skills:
```
npx skills add your-name/s1ft-client-digest --skill client-digest
```
They also need the base skill s1ft. Say so in your README.

To tell other people about it, post the repo in the Discussions category “Community skills” of the skills repo. The owner adds entries to the list at Community skills by hand, and s1ft doesn’t check the skills on that list.

Send a skill to the skills repo

If you want your skill to ship in the s1ft plugin, send it as a pull request to s1ft-app/skills. The CONTRIBUTING.md file in that repo has the full rules. The steps are:

Post your idea in Discussions, in the category “Ideas”. Say what the skill does and which meeting data it reads. Wait for a response before you open a pull request.
Fork the repo and add your skill as skills/<name>/SKILL.md.
Follow the shared skill rules. The main ones: get data through the s1ft skill, add an “Adapt this skill” section that says which parts a user may change, give the start time when you quote someone, and put no personal path or email address in the file.
If the skill describes how a person speaks, keep to the text rules. Describe the data, don’t judge the person, and give no score or grade. A reviewer checks these skills before they merge.

Run the checks from the repo root:

python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/python scripts/validate_skills.py
.venv/bin/ruff check .
.venv/bin/mypy scripts tests
.venv/bin/python -m pytest -m "not network"

Open the pull request. The same checks run in CI, and they must pass.

The owner decides which pull request merges. Nobody pushes to main, and a merged skill ships in the plugin s1ft.

Connect AI agents: install the base skill and the library skills.
s1ft command line reference: every command, option and exit code.
Meeting data files: the fields of the files your skill reads.
s1ft skills page: the library skills, with an example for each.