https://github.com/saadjs/skillctl
Go CLI for installing, syncing, listing, removing, and validating agent skills.
https://github.com/saadjs/skillctl
agent-skills ai-skills claude claude-code codex
Last synced: 5 days ago
JSON representation
Go CLI for installing, syncing, listing, removing, and validating agent skills.
- Host: GitHub
- URL: https://github.com/saadjs/skillctl
- Owner: saadjs
- License: mit
- Created: 2026-02-01T13:53:13.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T03:30:55.000Z (about 2 months ago)
- Last Synced: 2026-04-27T05:16:43.900Z (about 2 months ago)
- Topics: agent-skills, ai-skills, claude, claude-code, codex
- Language: Go
- Homepage:
- Size: 132 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# skillctl
Go CLI for installing, syncing, listing, removing, and validating agent skills.
> If you asked your agent to perform the same task twice, it should probably be a skill.
The personal skills that previously lived in this repository now live in
[`saadjs/agent-stuff`](https://github.com/saadjs/agent-stuff) under `skills/`.
## Install (Homebrew)
```sh
brew tap saadjs/homebrew-tap
brew install skillctl
```
## Install (manual)
Download the latest release for your platform from GitHub Releases, then:
```sh
tar -xzf skillctl___.tar.gz
sudo mv skillctl /usr/local/bin/skillctl
```
## Usage
```sh
# Show available commands
skillctl --help
skillctl --version
# Install to the new standard ~/.agents/skills directory (recommended)
skillctl add saadjs/agent-stuff --tool agents --scope global
skillctl add saadjs/agent-stuff --tool agents --scope project
# Or install to tool-specific directories
skillctl add saadjs/agent-stuff --tool codex --scope global
skillctl add saadjs/agent-stuff --tool codex --tool claude --scope global
skillctl add saadjs/agent-stuff --tool cursor --scope project
skillctl add saadjs/agent-stuff --tool claude --scope project
skillctl add ./path/to/skills-repo --dest /tmp/skills
skillctl add ./path/to/skills-repo --dest /tmp/skills --force
skillctl add saadjs/agent-stuff --list
skillctl add saadjs/agent-stuff --path skills --skill de-dupe --list
skillctl list --tool agents --scope global
skillctl remove --tool agents --scope project --skill de-dupe
# Update remote installs from their original source
skillctl update
skillctl update de-dupe
# Sync changed skills only (default)
skillctl sync
# Force re-sync of every selected skill, even if unchanged
skillctl sync --all
```
Aliases are available for common commands: `skillctl install` is the same as
`skillctl add`, `skillctl ls` is the same as `skillctl list`, and `skillctl rm`
is the same as `skillctl remove`.
### Listing Source Skills
Use `skillctl add --list` to print skill names available in a source
without installing them. `--list` supports source-selection flags such as
`--ref`, `--path`, and repeatable `--skill`, but it does not accept destination
or install behavior flags such as `--tool`, `--scope`, `--dest`, `--overwrite`,
`--skip`, `--force`, or `--dry-run`.
### Sync mode: `--all`
`skillctl sync` is checksum-aware by default: it only copies skills that changed since the last sync for each configured tool.
Use `skillctl sync --all` when you need a full refresh. It ignores stored checksums and re-copies every selected skill, which helps when local skill folders were manually edited, partially deleted, or drifted out of sync without source changes.
### Remote Updates
Remote installs are tracked in `~/.config/skillctl/state.yaml`. When you install from a GitHub repo, `skillctl` records the source, ref, skills path, selected skill names, and destination so they can be reinstalled later.
```sh
# Update every tracked remote install
skillctl update
# Update only selected tracked skills
skillctl update de-dupe readme-maintainer
# Preview updates without writing files or state
skillctl update --dry-run
```
Local path installs and sync operations are not tracked for `skillctl update`.
### Security Scan During Install
`skillctl add` performs a built-in security scan before installing skills. The scan checks the configured skills subtree (`--path`, default `skills`) in the source for suspicious commands, potential exfiltration patterns, and malicious agent instructions.
- If findings are detected, install is blocked by default.
- In interactive mode, you can confirm and continue.
- In non-interactive mode (`--yes`), rerun with `--force` to bypass.
- `--dry-run` on local sources executes the security scan, but does not install files.
- `--dry-run` on remote sources does not clone or scan, and requires at least one `--skill` value.
Example flows:
```sh
# Default behavior: blocked if findings are detected
skillctl add owner/repo --tool agents --scope global --yes
# Explicit bypass for automation/non-interactive environments
skillctl add owner/repo --tool agents --scope global --yes --force
# Local dry run still scans, but performs no install writes
skillctl add ./path/to/skills-repo --tool agents --scope global --dry-run --yes --force
# Remote dry run skips cloning/scanning and requires explicit skills
skillctl add owner/repo --tool agents --scope global --dry-run --skill de-dupe
```
### Supported Tools & Paths
| Tool | Global Path | Project Path |
| -------- | ---------------------------- | ------------------ |
| agents | `~/.agents/skills` | `.agents/skills` |
| codex | `~/.codex/skills` | `.codex/skills` |
| claude | `~/.claude/skills` | `.claude/skills` |
| cursor | `~/.cursor/skills` | `.cursor/skills` |
| windsurf | `~/.codeium/windsurf/skills` | `.windsurf/skills` |
| copilot | `~/.copilot/skills` | `.github/skills` |
## Skill Repo Structure
- `skills//SKILL.md` defines a skill, its triggers, and workflow.
## Setup (dev)
```sh
go build ./cmd/skillctl
make test
```