How to use skylls

For LLMs

Are you an AI agent? Read skylls.dev/llms.txt: the whole guide as plain Markdown, written for agents. Then install the skylls skill so your agent CLI knows how to use skylls (raw skill).

1. Install the skylls skill

skylls agent-skill -g -a all                     # Claude Code, Codex and Gemini, global
skylls add jcsancho/skylls/skylls -g -a all      # or straight from the public GitHub repo

No skylls yet? npm install -g @skylls/cli, then skylls setup (see Install).

2. Skills

Share: a skill is a whole capability (its SKILL.md recipe plus its scripts and files), published to its own private repo, so everyone you share it with runs the same skill, maintained in one place:

skylls push pdf -m "First version"     # ~/.claude/skills/pdf → <org>/skill-pdf (private)
skylls share pdf @bob                  # one skill to one friend (--all @bob for everything)

Use: find what you and your friends published and pull it into your agent:

skylls source add alice                # once: see what alice shared with you
skylls find pdf --json --limit 5       # search, compact output for agents
skylls add pdf -g -a all               # writes into ~/.claude/skills, ~/.agents/skills, ~/.gemini/skills (no -g: this project)

Overview

skylls is a command-line tool that sits on top of GitHub. It works with three kinds of items:

• Skills: folders with a SKILL.md that teach an agent CLI a capability (Claude Code, Codex, Gemini CLI).
• Agents: a long-lived agent's folder (CLAUDE.md/AGENTS.md, .claude/, scripts), with its Obsidian memory.
• Swarms: a team of agents working together, with their roles and memory.

Every item you publish gets its own private GitHub repo. GitHub stores everything and decides who can see what. skylls adds versions, changelogs, plain one-sentence summaries, folders, suggestions and a secret scan on top.

Install

With npm

Needs Node 18+ and Python 3.11+ (the npm package runs the Python tool).

npm install -g @skylls/cli
skylls setup

To try it without installing: npx @skylls/cli --version.

Installed it as @jcsancho/skylls before 1.4.0? Run skylls update: it moves you to @skylls/cli (or by hand: npm uninstall -g @jcsancho/skylls && npm install -g @skylls/cli).

With the installer (macOS / Linux)

curl -fsSL https://skylls.dev/install.sh | bash

The installer:

1. Checks git, uv, gh and gitleaks, and offers to install missing ones with Homebrew.
2. Installs skylls and puts it on your PATH.
3. Logs you in to GitHub.
4. Runs skylls setup.

Options go after the command: -y answers yes to everything, --no-setup only installs, --ref v1.0.0 installs a specific version. Example: curl -fsSL https://skylls.dev/install.sh | bash -s -- -y.

By hand

uv tool install git+https://github.com/jcsancho/skylls   # or: pipx install git+https://github.com/jcsancho/skylls
skylls setup

Requirements

• Required: Python 3.11+, git, and the GitHub CLI gh, logged in (gh auth login).
• For publishing: gitleaks (brew install gitleaks).
• Optional: the claude CLI, which writes the plain summaries for you.

Updating

skylls update                      # the newest version, installed the way you installed skylls
skylls update --check              # only check
skylls --version                   # check your version

On 1.2.2 or older (no skylls update yet), update once by hand: uv tool install --force git+https://github.com/jcsancho/skylls, or npm uninstall -g @jcsancho/skylls && npm install -g @skylls/cli if you installed with npm.

Setup

skylls setup runs once (any command starts it the first time) and asks four things:

1. Where to publish. We recommend a GitHub organization you administer. It works like a folder holding one private repo per item, keeps them apart from your other repos, and lets friends have read-only access.

   github.com/you-skylls          ← your organization
   ├── skill-pdf                  ← one private repo per skill
   ├── agent-lead-generator       ← one per agent (definition + memory)
   └── swarm-marketing-team       ← one per swarm

   If you don't have one, setup shows how to create it (free, about a minute, at github.com/account/organizations/new), can open the page and waits until it exists. It also offers to set the organization's base permission to No permission, so members see nothing by default. Type account to use your personal account instead; repos are then named skylls-skill-pdf and so on.
2. Your agent CLIs: claude, codex, gemini or all.
3. Your folders for agents and swarms (default ~/agents and ~/swarms).
4. The skylls skill: installs it globally so your agents can use skylls themselves (see For AI agents).

Without questions:

skylls setup --owner you-skylls --agents all --agents-dir ~/agents --swarms-dir ~/swarms

Your settings live in ~/.config/skylls/config.json. Run skylls setup again to change them.

Quick start

You publish a skill and share it with Bob:

$ skylls push pdf -m "First version"   # ~/.claude/skills/pdf → you-skylls/skill-pdf (private)
$ skylls share pdf @bob                # Bob may install it

Bob installs it:

$ skylls source add you-skylls        # once: accepts your shares, shows what you shared
$ skylls add pdf -g -a all            # installs it for Claude Code, Codex and Gemini

When you publish a new version, Bob gets it with skylls pull --update.

Find and install skills

skylls list                    # your skills and what friends shared, grouped by folder
skylls find invoice            # search names, folders, summaries and SKILL.md text
skylls find --folder docs      # one folder
skylls add pdf                 # install into this project
skylls add pdf -g -a all       # install globally for every agent CLI
skylls add pdf --from alice    # when several people have a "pdf"
skylls add pdf@1.2.0           # a specific (older) version
skylls log pdf                 # who made it, every version, what changed
skylls remove pdf              # remove your local copy (never touches GitHub)

Where skills go

-a picks the agent CLIs (claude, codex, gemini, all); without it, skylls uses the ones you chose at setup. A global install for several CLIs keeps one real copy (Claude's) and links the others to it.

Publish

skylls push pdf -m "Handles scans"        # 1.2.0 → 1.2.1 (default: patch)
skylls push pdf -m "New option" --minor   # 1.2.1 → 1.3.0
skylls push pdf -m "Rewrite" --major      # 1.3.0 → 2.0.0
skylls push pdf --folder docs             # also put it in a folder
skylls push ./path/to/skill               # or publish a folder by path

What happens on push:

• The repo: the first push creates the private repo <org>/skill-<name> (<you>/skylls-skill-<name> on a personal account). Each version is a git tag such as v1.3.0. Without -m, push asks what changed.
• Secret scan: before anything leaves your machine, push scans for API keys, tokens, passwords, private keys and personal data (emails, phone numbers…) with gitleaks. If it finds any, nothing is published. Use --skip-scan only for false positives.
• Changelog: skylls writes a CHANGELOG.md in each repo (don't edit it by hand). It holds a plain one-sentence summary (written by Claude, or yours with --about "…"), who created the item, and one entry per version: what changed, when and by whom. The summary is also the repo's description on GitHub.

Versions and updates

skylls installed               # installed skills; flags the ones with a newer version
skylls pull                    # check for newer versions
skylls pull --update           # install them
skylls sync -m "Small fixes"   # publish your changed items, then install friends' new versions
skylls add pdf@1.0.0           # go back to an older version

Every version stays installable, so you can always go back.

skylls sync does both directions in one go: it publishes a new version of every skill, agent and swarm you already published and changed since (each one is scanned for secrets; if one is refused, the others still go), then installs the newer versions of everything friends shared with you. Your copy of an agent's memory is refreshed to the owner's latest (--keep-memory keeps yours and puts theirs next to it). Add --dry-run to see what it would do.

Agents and swarms

Agents and swarms use the same commands, under skylls agents … and skylls swarms …:

skylls agents                                   # yours (published or not) and friends'
skylls agents push lead-generator -m "Adds LinkedIn"  # ~/agents/lead-generator → <org>/agent-lead-generator
skylls agents share lead-generator @bob
skylls agents add lead-generator --from alice   # → ~/agents/lead-generator
skylls agents add lead-generator@1.0.0 --from alice --as lead-generator-old
skylls agents remove lead-generator             # local folder → the Trash (repos untouched)
skylls swarms push marketing-team               # ~/swarms/marketing-team → <org>/swarm-marketing-team

What gets published

Only the definition, never runtime state:

To adjust this, put a .skyllsignore file in the folder: one pattern per line, !pattern to include something.

Installing a friend's agent or swarm

• It goes into your agents or swarms folder (for example ~/agents/lead-generator/).
• Absolute paths from their machine are rewritten to yours, and missing ones are listed.
• Running add again (or sync) updates the definition and refreshes your copy of its memory to the owner's latest; notes only you added stay, and so does your runtime data. Pass --keep-memory to keep your memory exactly as it is: the owner's latest goes next to it in its own folder (alice-wiki/ beside wiki/).
• Where it came from is recorded in its CHANGELOG.md.

Obsidian memory

An agent's or swarm's memory travels with it.

• Best place: inside the item's folder, for example ~/agents/lead-generator/wiki/. A subfolder counts as memory if it's an Obsidian vault (has .obsidian/) or is named memory, wiki, obsidian or *-wiki. All of it is published, except Obsidian's per-user window layout, the trash and files over 5 MB.
• Memory elsewhere in ~/Obsidian also works: skylls finds a <x>-wiki vault the instructions mention, or <vault>/AGENTS/<name>/. It's snapshotted into .skylls-memory/ and restored to the same place under your friend's home.
• Listing it yourself: a .skyllsmemory file in the item's folder lists memory folders.

Sharing

skylls share pdf @bob @carol   # invite to one item
skylls share --all @bob        # every skill you published
skylls share pdf               # who has access
skylls unshare pdf @bob        # revoke (what Bob installed stays on his machine)
skylls revoke @bob             # take back everything you shared with Bob (asks first)
skylls agents share --all @bob # every agent (swarms: skylls swarms share …)
skylls swarms share apps @bob --prs  # also let them send pull requests (asked when not given; --no-prs)

• Who sees what: friends see only the items you shared with them, and GitHub enforces it. skylls invites them to single repos as outside collaborators, who can't see your other repos, even in the same organization.
• Access level: with an organization, friends get read-only access. On a personal account, GitHub gives everyone you invite write access to that repo; skylls never pushes to friends' repos, but plain git could.

Seeing friends' items

skylls source add alice        # see what alice shared with you (accepts her invites)
skylls source                  # your friends and how many items each shared
skylls source remove alice

Who shares what

skylls shared                  # what you shared and with whom, what friends shared with you
skylls shared @bob             # only between you and Bob
skylls people                  # per person: what you share with them, what they share with you

Both also list what isn't accepted yet: your invites a friend hasn't accepted (with the date you sent them), and items shared with you that wait for you, with the skylls source add command that accepts them.

Run source add once per friend (their GitHub login or organization). Later shares from that friend are accepted automatically. If someone you haven't added shares with you, skylls list tells you, and you decide whether to add them.

Suggestions

Only the owner publishes an item. Friends suggest improvements, which become GitHub issues in the owner's repo:

skylls suggest pdf --from alice "Also handle scanned PDFs"   # an issue in alice's repo, assigned to her
skylls suggestions                                           # open suggestions for your items
skylls accept pdf#3 -m "Done in 1.3.0"                       # closes it as done
skylls decline pdf#4 -m "Out of scope"                       # closes it as not planned

Pull requests (agents and swarms)

Changed your copy of a friend's agent or swarm and want them to have it? Send it as a real GitHub pull request. They review it and, when they accept, skylls merges it into their copy and publishes a new version, which you install like any update.

# the owner, once per item (or --all): let the people they share with send pull requests
skylls swarms allow-prs opportunity-hunter

# you: compare your copy with the version you installed and send the difference
skylls swarms propose opportunity-hunter --from alyssa -m "Add the new data tools"

# the owner: review and answer
skylls swarms suggestions                        # opportunity-hunter#3  Add the new data tools  (pull request)
skylls swarms review opportunity-hunter#3        # the diff, and a warning if you changed the same files
skylls swarms accept opportunity-hunter#3        # applies it to your folder, publishes a new version, closes it
skylls swarms decline opportunity-hunter#3 -m "I keep my helpers"

• propose lists the changed files (leave some out with --skip FILE), scans them for secrets, puts the owner's paths back (an install points them at yours), forks the repo privately into your account or organization (<repo>-from-<owner>) and opens the pull request.
• accept stops if the owner changed a file the pull request also changes since the version it started from; --force takes the proposal.
• Memory and skills shared by reference are never part of a pull request.
• Accept with skylls, not on github.com: a merge there would be overwritten by the owner's next push.
• Sharing an agent or swarm asks whether the people you share it with may send pull requests (--prs / --no-prs answer it up front). It's one switch per item: everyone you share that item with can, or nobody.
• allow-prs --off turns it off again. For an organization, allow-prs also allows private forks in it.

Folders

GitHub has no folders for repos, so skylls uses topics:

skylls push pdf --folder docs  # or later: skylls move pdf docs   ('.' = no folder)
skylls folder                  # your folders and how many items each has
skylls folder rename docs office
skylls folder remove office    # items stay, just without a folder
skylls list -f docs            # filter (also: find -f docs)

On GitHub, filter your repos by topic: github.com/<owner>?tab=repositories&q=topic:docs.

The dashboard

The dashboard does the sharing side of skylls from your browser. Sign in with GitHub and you can:

• Yours: see your skills, agents and swarms (tabs), with version, folder and summary. Click Who can see it to list the people with access, share with a GitHub user, or remove someone.
• Shared with you, waiting: accept invitations friends sent you.
• Open suggestions: accept or decline them, with a note.
• Friends' items: copy the install command for anything friends shared with you.

Publishing and installing still happen in the terminal: the dashboard has no access to your computer.

GitHub asks for the repo and read:org permissions, needed to read your private skylls repos and manage who can see them. The dashboard only touches skylls repos. It has no database: your token is kept in an encrypted cookie in your browser for up to 30 days, and signing out deletes it. Read the privacy policy for details.

Security and privacy

• Private repos only. Every item repo is created private. If skylls finds one that is public, it warns you and offers to make it private.
• Nothing shared by default. Friends are invited to single repos, never to your whole account or organization.
• Secret scan on every push. gitleaks checks for keys, tokens, passwords and personal data before anything is uploaded, and the push stops if it finds any.
• Definitions, not state. Agents and swarms never publish logs, data, local settings, env files or keys (see what gets published).
• No skylls server for your data. The CLI talks directly to GitHub with your own gh login. The dashboard has no database and keeps your token only in an encrypted cookie.
• Read what you install. A skill is instructions your agent follows. Install items from people you trust, and check skylls log <name> to see who changed what.

For AI agents

Setup installs the skylls skill, which teaches Claude Code, Codex and Gemini to use skylls: install it if it's missing, find and install skills, agents and swarms, and ask you before publishing or sharing anything. So you can just ask your agent: "find a skill for PDF forms and install it".

skylls agent-skill -g -a all                     # install (or reinstall) it later
skylls add jcsancho/skylls/skylls -g -a all      # or straight from GitHub

After an upgrade, the next skylls command updates your installed copy.

JSON output

With --json, read commands print one compact JSON object per line on stdout, without empty fields. Messages and errors go to stderr.

$ skylls find pdf --json --limit 5
{"name":"pdf","owner":"alice","folder":"docs","version":"1.3.0","summary":"Fills in PDF forms for you.","updated":"2026-10-07","repo":"alice-skylls/skill-pdf"}

skylls installed --json        # "newer" when an update exists
skylls log pdf --json          # details + version history
skylls agents list --json      # "published":false for ones not published yet

find --json returns at most 10 results unless you pass --limit.

Public skills from skills.sh

skylls search pdf                          # top matches on skills.sh, with install counts
skylls add anthropics/skills/pdf -g        # install straight from a public GitHub repo

How it works

<org>/skill-pdf            ┐  one private repo per item, only what friends may see
<org>/agent-lead-generator │  + CHANGELOG.md, tags v1.0.0…, topics (folder)
<org>/swarm-marketing-team ┘  (personal account: skylls-skill-pdf, …)
        ▲ push (copy, commit, tag)              │ add (copy the version you want)
        │                                       ▼
~/.claude/skills/pdf   ~/agents/lead-generator   ~/swarms/marketing-team   ← your copies / workspaces

• Config: ~/.config/skylls/config.json holds your login, where you publish, your agent CLIs, your folders and your friends.
• Finding items: two GitHub GraphQL queries (the repos you can access, then the skylls repos' changelogs and instructions).
• Publishing and installing: small clones in ~/.cache/skylls/repos/.
• Your folders: ~/agents and ~/swarms are just your workspaces. skylls never commits there.
• Naming: in an organization repos are skill-…, agent-…, swarm-…; on a personal account skylls-skill-… and so on. A repo only counts as a skylls item if it has the skylls topic, which skylls sets.

Command reference

Run skylls help for the same list in your terminal.

FAQ

Can a friend see my other skills?

No. Each item is its own private repo, and friends are invited to single repos only. GitHub enforces it.

What happens to a friend's copy when I unshare?

What they already installed stays on their machine. They just can't get new versions.

Can friends change my skill?

No. Only you publish. Friends send suggestions, and for agents and swarms also pull requests with their changes; you accept or decline.

The secret scan stopped my push, but it's a false positive.

Check the finding first. If it really is safe, push again with --skip-scan.

Two friends have a skill with the same name.

Pick one with --from <owner>, for example skylls add pdf --from alice.

Where do I report a bug?

Open an issue at github.com/jcsancho/skylls/issues.