Skills for agents

Agent Skills is an open standard: a folder with a SKILL.md (instructions for the agent) and, when needed, scripts/, references/ and assets/. Claude Code, Codex, Cursor and other agents read it.

On SetFork every published public list is a skill — there is nothing extra to build. Steps become the instructions, commands become a script, and files the author put into the list travel with it.

How to spot a skill

A skill has a Skill badge next to its name (templates have a Template badge). Find them all with is:skill in search. The author sets it in the list settings ("Skill for agents"); publish_skill and sf skill publish set it themselves. Below the list, a Skill files block shows scripts/, references/, assets/ as a file tree; a click opens the file's text.

Install a skill

npx skills add https://setfork.com/<owner>/<slug>/skill.tar.gz

The command is on the list page: Get → Embed → Skill for your agent, next to the "Open SKILL.md" and "Download the skill archive" links.

To install a specific version, add ?ref=: a release tag or a version number.

npx skills add "https://setfork.com/<owner>/<slug>/skill.tar.gz?ref=v1.2.0"

The steps and files then come from that version even after the list moves on. The title, description and skill header stay current. An unknown tag is a 404 — the server never substitutes the current version.

The agent downloads the skill without signing in, so the command works only for a published public list. Private lists and drafts don't show it — the agent would get a 404. The files themselves still open in your browser while you are signed in.

To check a downloaded skill against the standard, run skills-ref validate <folder>.

What is inside

<name>/
  SKILL.md              # the instructions: the list's steps and text in order
  scripts/run.sh        # the steps' commands — the same script as /raw
  scripts/…, references/…, assets/…   # the author's files, if any

• SKILL.md header. name comes from the list address (Latin letters, up to 64 characters), description from the list description, or from the title when there is none. The agent decides whether to use the skill by the description, so say what the skill does and when to use it. metadata carries the list link, the version number (setfork-version) and its commit SHA (setfork-sha), so you can tell exactly which revision you installed. If the skill came in as its own SKILL.md, its license, compatibility, allowed-tools and metadata keys come back as they were; a clone keeps them in list.json as skillHeader. To drop the header over git, write "skillHeader": {}.
• Text stays in place. The list's text blocks go into SKILL.md between the steps, where they sit on the page.
• Dangerous steps are marked. A step with a destructive command comes marked ⚠ DESTRUCTIVE and is commented out in scripts/run.sh. A step flagged "needs a human" comes marked 🧑 NEEDS A HUMAN: the agent stops there and asks. The instructions open with a warning that the text came from a list, not from you.
• The author's files win. If the author ships their own scripts/run.sh, the archive carries theirs.

Publish your own skill

A skill on SetFork is a list, so it is published the way any list is. The one difference: the author's files go in through git.

1. Text — steps and description

Any way you like:

• on the site — "New list", steps and text blocks;
• over MCP — create_list, then patch_list (see MCP server). This is the easy way to bring an existing SKILL.md: the agent splits it into blocks;
• over git — by editing list.json (see Git access).

2. Files — scripts/, references/, assets/

The owner or a collaborator adds them in one of three ways:

• on the site — the "Skill files" section of the list editor (shown for a skill and for a list that already has files): add, edit, remove. The change goes into the same version as the steps;
• with sf or MCP — sf skill publish and publish_skill (below);
• over git — the password is an API token with the write scope:

git clone https://setfork.com/<owner>/<slug>.git
cd <slug>
mkdir -p scripts references
cp ~/my-skill/scripts/* scripts/
cp ~/my-skill/references/* references/
git add scripts references
git commit -m "Skill files"
git push

What the server checks on push:

• only these three folders, one level deep — no subfolders;
• text only — binary files are refused;
• at most 50 files and 1 MB across all three folders;
• scripts/ goes through the same destructive-command check as steps; the refusal names the file;
• access keys (GitHub, AWS, OpenAI, Anthropic, OpenRouter, Slack, Stripe, Yandex Cloud tokens, private keys and more) are refused everywhere — in files, steps and the title. The refusal names the file and line and shows only the start of the key.

Keys are searched in every commit of the push, not just the last one: git clone hands out the whole history, so a key added in one commit and removed in the next still leaks. If the refusal says path@commit, the key is in the history — remove it from that commit (git rebase), not from the current file. Revoke a key that has been shared anywhere with its provider: deleting it from the list does not undo that.

Editing the steps on the site keeps the files: when they are not touched, a new version carries them over from the previous one. The site checks files the same way: a dangerous command in a script or a key in a file is a warning on save and a refusal on publish, naming the file.

3. Publish and open it up

The list has to be published and public — otherwise an agent without a login can't download it. To publish a draft: "…" → "Publish" on the list page, or publish_draft over MCP.

4. Name the version — a release

The SetFork version number (v3) grows with every edit. A name for people — 0.5.1, v1.2.0 — is a release: a tag on a version with a title and notes. Publish it on the Releases page or from an agent with MCP create_release (see Versions and releases).

One command: sf

The sf CLI (in the spirit of gh) publishes a whole skill folder — SKILL.md, scripts/, references/, assets/ — as one version:

sf auth login                              # once, a token with the write scope
sf skill publish ./my-skill                # a new draft
sf skill publish ./my-skill owner/slug     # a new version of an existing list
sf release create owner/slug v1.2.0 --notes-file CHANGELOG.md --yes

The folder is the truth: files missing from it are removed from the list. Steps and text come from SKILL.md: numbered items become steps, everything else text blocks. An agent does the same with the MCP tool publish_skill.

Release from GitHub: an Action

If the skill lives in a GitHub repository, every pushed tag can become a version of the list and a release under the same tag:

# .github/workflows/setfork.yml
on:
  push:
    tags: ['v*']
permissions: {}
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: mikey-semy/setfork-app/cli@<commit-sha>
        with:
          list: owner/slug
          token: ${{ secrets.SETFORK_TOKEN }}
          path: skills/my-skill

SETFORK_TOKEN is an API token with the write scope stored in the repository secrets. The folder is the truth, as with sf skill publish. Re-running the job for a tag that is already released publishes nothing. All inputs are in the CLI README.

Recipe: move an existing skill over

This is how review-kit moved to SetFork:

1. Ask an agent with MCP connected to create a list from the SKILL.md: the description into the list description, sections and steps into blocks.
2. Publish it as private — the list gets versions and a git repo, but nobody else sees it.
3. Clone the list and add scripts/, references/, assets/ in one commit (step 2 above).
4. Make the list public.
5. Publish a release with the same tag as the original skill.
6. Check it: npx skills add …/skill.tar.gz, then skills-ref validate.

Import someone else's skill

A skill on GitHub can be brought in as a draft of yours: on the New list page use "Import a skill from GitHub", over MCP import_skill, in a terminal sf skill import <address>. The address is the same as for npx skills add: the repository, the skill folder or its SKILL.md. Everything comes from one commit, and the link to it stays under the list title.

Visibility follows the license.

• An open license (MIT, Apache-2.0, BSD, GPL, CC-BY and others that allow redistribution) — the draft can be published; the title shows where it came from and under which license.
• No license, a proprietary or a non-commercial one — the list is private only: neither the settings nor a "use as template" copy can make it public.

The license comes from the license: field of the SKILL.md header or from the LICENSE file. Anything not recognised counts as closed. Files in subfolders, binary files and files over 1 MB are not brought over — the import names each.

Known gaps

• Metadata at a tag is current. ?ref= serves the steps and files of that version, but the current title, description and header.
• A push brings text and files as two versions. Over git push they arrive as separate commits; sf skill publish and publish_skill land them in one version.