skylls

Share agent skills, agents and swarms with friends through GitHub, one item at a time.

Every skill, agent and swarm you publish gets its own private GitHub repo. You decide, item by item, who may install it. Friends do the same with theirs. skylls installs what you were given: skills for Claude Code, Codex or Gemini CLI (in one project or globally), and agents and swarms together with their Obsidian memory.

skylls is a layer on top of GitHub. GitHub stores everything and enforces who can see what (repo access). skylls adds versions, changelogs, plain summaries, folders, suggestions and a secret scan.

Install

One command (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: -y answers yes to everything, --no-setup only installs, and --ref v1.0.0 installs a specific version. Pass them after the command: curl -fsSL https://skylls.dev/install.sh | bash -s -- -y.

With npm (needs Node 18+ and Python 3.11+; the package runs the Python tool):

npm install -g @skylls/cli && skylls setup      # or try it: npx @skylls/cli --version

Installed it as @jcsancho/skylls before 1.4.0? skylls update moves you to @skylls/cli.

Or by hand: uv tool install git+https://github.com/jcsancho/skylls (or pipx install …), then skylls setup.

Update with skylls update (--check only looks), which reinstalls the newest release the way you installed it (uv, pipx or npm). Check your version with skylls --version; CHANGES.md lists what changed in each.

Setup

skylls setup (any command runs it the first time) asks:

1. Where to publish. Recommended: a GitHub organization you administer. It is listed first and is the default, and it works like a folder holding one independent private repo per item:

   github.com/<you>-skylls          ← your organization
   ├── skill-pdf                    ← one private repo per skill
   ├── agent-btc                    ← one per agent (definition + memory)
   └── swarm-apps_ideas             ← one per swarm
   

   It keeps them apart from your other repos and lets friends have read-only access. If you don't have one yet, setup shows how to create it (free, about a minute, at github.com/account/organizations/new), can open that page for you, and waits until it exists. Type account to use your personal account instead; there repos are named skylls-skill-pdf etc., so they stand apart from your other projects. Setup also checks the organization's base permission (what members can see) and offers to set it to "No permission", so nothing is visible until you share it.

2. Your agent CLIs: claude, codex, gemini or all.

3. Your folders for agents and swarms (default ~/agents, ~/swarms).

4. The skylls skill: install it globally so Claude Code, Codex and Gemini can use skylls themselves (default: all three; --no-agent-skill skips).

Non-interactive: skylls setup --owner <you-or-org> --agents all --agents-dir D --swarms-dir D.

Quick start

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

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

Find and install

skylls list                         # your skills and what friends shared, grouped by folder
skylls find invoice                 # search name, folder, summary and SKILL.md text
skylls find --folder docs           # one folder
skylls add pdf                      # this project: ./.claude/skills/pdf (+ ./.agents, ./.gemini)
skylls add pdf -g -a all            # global: ~/.claude/skills/pdf, Codex/Gemini link to it
skylls add pdf --from alice         # when several people have a "pdf"
skylls add [email protected]                # an older version
skylls log pdf                      # who made it, every version, what changed
skylls installed                    # installed skills, flags newer versions
skylls pull --update                # install newer versions
skylls sync -m "Small fixes"        # publish every published item you changed (skills, agents,
                                    # swarms; each one scanned), then install the newer versions
                                    # of skills, agents and swarms friends shared with you
                                    # (no -m: never asks; the log lists the changed files;
                                    # --keep-memory: keep your agents'/swarms' memory as it is;
                                    # unchanged items are checked on this computer, not GitHub;
                                    # only the repos friends shared are listed there; changes
                                    # others pushed to your items, e.g. a friend with write
                                    # access, are copied into yours first; what friends newly
                                    # shared is installed, skills globally; shares from people
                                    # who aren't your sources are listed with how to accept them)
skylls view                         # only list what sync would publish (with the changed files)
                                    # and which newer versions and new shares it would install,
                                    # shares waiting for you to accept, plus what is on
                                    # GitHub but not on this computer; changes nothing
skylls remove pdf                   # remove your local copy (never touches GitHub)

Where skills go:

	Claude Code	Codex	Gemini
skylls add pdf (this project)	./.claude/skills/pdf/	./.agents/skills/pdf/	./.gemini/skills/pdf/
skylls add pdf -g (global)	~/.claude/skills/pdf/	~/.agents/skills/pdf/	~/.gemini/skills/pdf/

A global install for several agents keeps one real copy (Claude's) and links the others to it. -a picks the agents (default: those chosen at setup).

Publish

skylls push pdf -m "Handles scans"          # 1.2.0 → 1.2.1 (default)
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 a folder path

• 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 (v1.3.0), and without -m push asks what changed.
• Secret scan: before anything goes up, push scans for API keys, tokens, passwords, private keys and personal data (emails, phone numbers…) with gitleaks, and publishes nothing if it finds any. Example values cut short or blanked out ("sk-proj-abc…", xxxxxx, <your-key>) are ignored. For other findings, push and sync (in a terminal) ask whether they are false positives: answer yes and they are published and remembered (hashed, in ~/.config/skylls/allowed-secrets.json), so you aren't asked about them again. --skip-scan skips the scan altogether.
• CHANGELOG.md: each item has one, written by skylls (don't edit it). It holds a plain one-sentence summary (written by Claude through claude -p, or yours with --about "…"), who created it, and one entry per version: what changed, when and by whom. The summary is also the repo's description on GitHub.

Agents and swarms

The same commands, under skylls agents … and skylls swarms …:

skylls agents                                # yours (published or not) + friends'
skylls agents push btc -m "Adds ETH"         # ~/agents/btc → <org>/agent-btc
skylls agents share btc @bob
skylls agents add btc --from alice           # → ~/agents/btc
skylls agents add [email protected] --from alice --as btc-old
skylls agents remove btc                     # local folder → the Trash (repos untouched)
skylls swarms push apps_ideas                # ~/swarms/apps_ideas → <org>/swarm-apps_ideas

What is published is the definition, never runtime state:

	published	not published
agent	CLAUDE.md/AGENTS.md/GEMINI.md, .claude/ (settings, skills, commands), scripts and other files, its memory folder	logs/, data/, reports/, scratch/, state/, caches and venvs, *.log, *.jsonl, *_state.json, databases, .claude/settings.local.json, .env*, keys, files over 100 MB (GitHub's limit; publish lists them)
swarm	top-level and per-role CLAUDE.md/AGENTS.md/GEMINI.md and .claude/, .swarm/agents.json, .swarm/schedules.json, its memory folder	the roles' work files, reports, .swarm/bus.jsonl and other state

A .skyllsignore in the folder adjusts this (one pattern per line, !pattern to include something).

Skills inside an agent or swarm (.claude/skills/<name>/, also per role) that are one of your skylls skills are published as a reference, not a copy: a .skylls-skills file lists them, and installing the agent or swarm puts the latest version of each in place from skylls. Share those skills too (skylls share <name> @user); a friend who can't see one is told to ask for it. Other skills in there are published as copies.

Memory (Obsidian) travels with them.

• Where it should live: inside the agent's or swarm's folder (e.g. ~/agents/btc/wiki/). A subfolder counts as memory if it is 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, its downloaded plugins and themes (.obsidian/plugins/, .obsidian/themes/), the trash and files over 100 MB (GitHub's limit; publish lists them).
• Private notes stay home: a note whose frontmatter has private: true is never published (client names, people, deals). Keep what friends may learn from (method, lessons, playbooks) in plain notes; .skyllsignore can also leave out whole paths.
• You see what goes out: push lists the memory notes that are new or changed since the last version and asks before publishing them (-y publishes without asking; --dry-run only lists them). sync publishes them without asking and says how many went out; skylls view lists them first.
• Memory elsewhere in ~/Obsidian still works:
  • Found from the instructions: a <x>-wiki vault they mention, or <vault>/AGENTS/<name>/ for the item's own name.
  • Snapshotted into .skylls-memory/, and restored to the same place under a friend's home.
  • A .skyllsmemory file lists memory folders yourself.

Installing a friend's agent or swarm:

• Where it goes: your agents or swarms folder (~/agents/btc/).
• Paths: absolute paths from their machine are rewritten to yours, and missing ones are listed.
• Updates: 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; your runtime data stays). 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/, ~/Obsidian/alice-btc-wiki).
• Where it came from is recorded in its CHANGELOG.md.

Friends and sharing

skylls share pdf @bob @carol        # invite to one item
skylls share --all @bob             # every skill you published (agents/swarms: skylls agents share --all @bob)
skylls share pdf                    # who has access
skylls swarms share apps @bob --prs # agents/swarms: also let Bob send pull requests (asked when not given; --no-prs)
skylls unshare pdf @bob             # revoke (what Bob installed stays on his machine)
skylls revoke @bob                  # take back everything (skills, agents, swarms, pending invites)
skylls shared                      # what you shared and with whom + what friends shared with you
skylls shared @bob                 # only between you and Bob
                                   # (also lists invites not accepted yet, both ways)
skylls people                      # each person: what you share with them, what they share with you

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 sees what: nothing is shared by default. Your 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. Don't make friends members of your organization: members get its base permission on every repo, which setup offers to set to "No permission". New shares from a friend you added are accepted automatically. If someone else shares with you, list says so and you decide whether to add them.
• Access level: on a personal account, GitHub gives everyone you invite write access to that repo. skylls never pushes to friends' repos, but plain git could. With an organization, skylls invites friends read-only.

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. Every skylls repo also carries the topics skylls and skylls-skill / skylls-agent / skylls-swarm. In an organization repos are named skill-…, agent-…, swarm-…; on a personal account skylls-skill-… and so on. A repo only counts as a skylls item if it carries the skylls topic (skylls sets it), so other repos with similar names are ignored.

Suggestions

skylls suggest pdf --from alice "Also handle scanned PDFs"   # a GitHub issue in alice's repo, assigned to her
skylls suggestions                                           # open suggestions for yours
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 then 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"
#   → lists the changed files (leave some out with --skip scout/CLAUDE.md), scans for secrets,
#     puts the owner's paths back (an install points them at yours), forks the repo into your
#     account/organization (private) and opens the pull request

# 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"

accept stops if you changed a file the pull request also changes since the version it started from (--force takes theirs). Memory and skills shared by reference are never part of a pull request. Merging on github.com instead would be overwritten by your next push: accept with skylls.

For agents: few tokens

Setup installs the skylls skill (skylls/skills/skylls/SKILL.md), which teaches Claude Code, Codex and Gemini to use skylls:

• What it covers: installing skylls if it's missing; finding and installing skills, agents and swarms; asking you before publishing or sharing anything.
• Installing it later: skylls agent-skill -g -a all, or from GitHub: skylls add jcsancho/skylls/skylls -g -a all.
• Updates: after an upgrade, the next skylls command updates your installed copy.

With --json, the 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.

Website and dashboard

webapp/ holds the skylls website and dashboard, deployed on Vercel. Sign in with GitHub to manage everything from the browser:

• Your items: see your skills, agents and swarms (version, folder, summary), and who can see each one. Share with a user, or remove someone.
• Invitations: accept what friends shared with you.
• Suggestions: accept or decline them, with a note.
• Friends' items: copy the install command for anything friends shared.

It has no database: it works directly on your GitHub with your own access, and keeps your token in an encrypted cookie. Deployment and local testing are described in webapp/README.md.

Public skills from skills.sh

skylls search pdf                          # top matches with install counts
skylls add anthropics/skills/pdf -g        # install straight from that public GitHub repo

Add --dry-run to any command to see what it would do without changing anything.

How it works

<org>/skill-pdf      ┐  one private repo per item, only what friends may see
<org>/agent-btc      │  + CHANGELOG.md, tags v1.0.0…, topics (folder)
<org>/swarm-apps     ┘  (personal account: skylls-skill-pdf, …)
        ▲ push (copy, commit, tag)        │ add (copy the version you want)
        │                                 ▼
~/.claude/skills/pdf   ~/agents/btc   ~/swarms/apps       ← 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 own folders: ~/agents and ~/swarms are just your workspaces. skylls never commits there. If they are git repos of your own (backups), that's up to you.

Command reference

Command	What it does
setup [--owner O] [--agents A] [--agents-dir D] [--swarms-dir D] [--no-agent-skill]	Your account or organization, agent CLIs, folders, the skylls skill
list [query] [--from O] [-f F]	Your items and what friends shared, grouped by folder
find <words> [--from O] [-f F] [-n N]	Search; shows summary, version, owner, folder
add <name[@ver]> [--from O] [-g] [-a A] [-y]	Install a skill (owner/repo/skill: from a public repo)
log <name> [--from O]	Who made it, versions, what changed
installed [-g] [-a A]	Installed skills and newer versions
pull [--update]	Check for (and install) newer versions
sync [-m msg] [--skip-scan] [-y] [--keep-memory]	Publish your changed items, then install friends' newer versions and what they newly shared; lists shares waiting for you to accept
view	What sync would publish (with the changed files) and install, and what is on GitHub but not on this computer; changes nothing
remove <name> [-g] [-a A]	Remove a local skill copy
push <name|path> [-m msg] [--minor|--major] [--about text] [--folder F] [--skip-scan]	Publish a new version to its private repo
share <name> @user… | --all @user	Let friends install it (no users: who has access)
unshare <name> @user… | --all @user	Revoke access
shared [@user…]	What you shared (with whom) and what friends shared with you
revoke @user… [-y]	Take back every skill, agent and swarm you shared with them
people	Who you share with and who shares with you, and what goes each way
move <name> <folder>	Put it in a folder (. = none)
folder [rename old new | remove F]	Your folders

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, for the automatic plain summaries.
• No Python dependencies.

License

Apache License 2.0. See LICENSE and NOTICE.