developer-skills-manager

Developer Skills Manager

Repository: adwise/developer-skills-manager. CLI command: skills-manager.

A Git-native CLI for installing agent skills as plain files. Bring your own public or private Git repository; there is no central registry, account service, or bundled company catalog.

Install and configure

Homebrew (Adwise tap)

Install the stable release from the Adwise tap:

brew install adwise/brew/skills-manager
skills-manager init --source git@github.com:example/team-skills.git
skills-manager

Upgrade with brew update && brew upgrade --formula adwise/brew/skills-manager. The stable formula pins a published release and its SHA-256 checksum. Until bottles are published for your platform, installation builds from source with Go. While the tap or bottles remain private, follow the tap's authentication instructions; the public Go installation below does not require tap access.

For an installation made with --HEAD, explicitly fetch the latest commit when upgrading; brew update only refreshes Homebrew and its taps:

brew upgrade --formula --fetch-HEAD adwise/brew/skills-manager

Always use the full formula name: the unqualified name skills-manager can also refer to an unrelated Homebrew cask.

To switch from --HEAD to stable, uninstall and reinstall the CLI. This does not remove your skills or configuration:

brew uninstall --formula adwise/brew/skills-manager
brew install adwise/brew/skills-manager

Automatic releases

Every push to main that passes tests, vet, and the installation smoke test publishes a GitHub release tagged v0.1.<workflow run number>. Pull requests do not publish releases. Re-running a successful workflow reuses its release rather than creating another version.

The Adwise tap's Update skills-manager release workflow checks for new releases every 15 minutes (GitHub scheduling can be delayed), updates the stable formula and checksum, and commits to the tap's main branch. It also supports manual dispatch. Both repositories' workflows must be merged into main and Actions must be allowed to write repository contents; tap branch protection must permit its updater to push. No cross-repository token is needed because the CLI releases are public. Bottles are not automatically published by this updater; Homebrew can build from source.

A stable install gets the newest release already synchronized into the tap, not necessarily the latest main commit. Use --HEAD if you explicitly want unreleased code. Existing HEAD installations are not switched to stable automatically.

Go install (public, no Homebrew required)

Requires Go 1.23+:

go install github.com/adwise/developer-skills-manager/cmd/skills-manager@latest
export PATH="$(go env GOPATH)/bin:$PATH"
skills-manager --help
skills-manager init --source git@github.com:example/team-skills.git
skills-manager

Go puts the executable in $(go env GOPATH)/bin by default. Add the PATH line to your shell profile (~/.zshrc or ~/.bashrc) to keep it available in new terminals. If you set GOBIN, add that directory to PATH instead. Repeat go install ...@latest to upgrade. Git and access to your source repository are required to fetch skills; Go installation itself does not require access to the private Adwise tap or catalog.

Local build

From a checkout of this repository:

go build -o build/skills-manager ./cmd/skills-manager
./build/skills-manager init --source /path/to/team-skills
./build/skills-manager

Private repositories use your existing Git SSH or credential-helper configuration. Do not embed access tokens in repository URLs; the source URL is saved in configuration and may appear in output.

init checks that the source has a skills/ directory and atomically saves the source and namespace in ~/.config/skills-manager/config.json. Local paths are saved as absolute paths. Full package and manifest validation happens when listing/installing skills or running validate.

Global installations live in ~/.agents/skills/skills-manager/. To use another namespace, including an existing installation directory:

skills-manager init --source git@github.com:example/team-skills.git --namespace team

This uses ~/.agents/skills/team/; it does not move or remove existing skills. One configured source is supported at a time. Use a different namespace and cache when managing a second source with --source; changing sources does not migrate installed skills.

Options work before or after commands. Precedence is flags > environment > saved configuration > defaults:

Only source and namespace are persisted by init; home and cache overrides apply to that invocation.

Commands

skills-manager                            Interactive installer (default)
skills-manager --help                     Show help
skills-manager init --source <url-or-path>  Configure a source repository
skills-manager available [query]          List or search skills
skills-manager sets                       List skill sets
skills-manager list                       List global and repository-owned skills
skills-manager install                    Interactive multi-select installer
skills-manager install <name|@set>...      Install skills or sets
skills-manager tui                        Interactive installer
skills-manager uninstall <name>           Remove a global installation
skills-manager diff [name]                Review upstream changes
skills-manager update [name]              Update one or all global installations
skills-manager doctor                     Check source, installs, and local skills
skills-manager validate [path]            Validate a package or repository

The installer marks installed skills with ✓ and updates with ↑. Use arrows to move, space to select, d to mark a removal, enter to apply, and q to cancel. Repository-owned skills in .agents/skills/ are never removed or updated by the installer.

Press b in the installer for the “Blackjack and hookers” easter egg (just blackjack, no money or saved scores). Use h to hit, s to stand, and n for a new round after the result. The dealer stands on soft 17. Press q or escape to return without changing your skill selections; Ctrl+C cancels the installer.

Skill repository format

team-skills/
├── skills.json                       # Optional sets, dependencies, and external entries
└── skills/
    ├── code-review/SKILL.md
    └── personal/test/SKILL.md

Each SKILL.md starts with frontmatter:

---
name: personal-test
description: A useful test workflow.
---

The frontmatter name is always the catalog ID. A package directly under skills/ must use its directory name (skills/code-review/SKILL.md uses name: code-review). A nested package can use either its directory name (skills/adwise/agent-browser/SKILL.md uses name: agent-browser) or its immediate parent and directory name joined by a hyphen (skills/personal/test/SKILL.md uses name: personal-test; skills/git/pull-request/SKILL.md uses name: git-pull-request). Use that ID in commands, skill sets, and dependencies.

Standalone validation also accepts a package whose name matches its leaf directory, so installed packages can be validated and checksummed under their full catalog ID. Local discovery accepts both forms for nested packages; frontmatter names must remain unique across the catalog. Explicit external IDs keep their namespace semantics and must end with the external package's frontmatter name. Names and path segments use lowercase letters, digits, and hyphens. Additional package files can be referenced using relative paths inside the package.

An optional skills.json defines sets, skill dependencies, and pinned external skills:

{
  "externalSkills": [
    {
      "id": "vercel/agent-browser",
      "repository": "https://github.com/vercel-labs/agent-browser.git",
      "ref": "aff6125c023b810ea3f2e5deec5379e9a4270bdc",
      "path": "skills/agent-browser"
    }
  ],
  "skillSets": [
    {
      "name": "review",
      "description": "Review workflows.",
      "skills": ["code-review"]
    }
  ]
}

Install with skills-manager install @review personal-test. External refs must be full 40- or 64-character commit hashes. External checkouts are shallow, partial, and sparse: only the requested package is materialized.

Skill dependencies

Declare dependencies by their exact catalog IDs in skills.json:

{
  "dependencies": {
    "skill-a": ["tools/mcporter"]
  }
}

Both skills must exist in the catalog (under skills/ or in externalSkills). Dependencies can have dependencies of their own. Install commands, sets, and the interactive installer automatically install the complete dependency chain, once per skill, dependencies first. Missing skills, duplicate dependencies, and cycles are rejected before installation.

Updating a skill also updates its dependencies and installs newly required ones. Existing differing packages are never overwritten by install; use update explicitly. Dependencies are not automatically removed when uninstalling a skill, and manual uninstall can still remove a dependency needed by another skill. This declares dependencies on skills, not on binaries: installing a mcporter skill does not install the mcporter executable.

Safety

The CLI validates frontmatter, paths, relative references, package boundaries, file types, external entries, and set membership. It rejects package symlinks and traversal. Copies are verified by SHA-256 before an atomic install/update swap. Updates use Git history; review them with diff first.

There are no post-install hooks, automatic script execution, or symlink farms. Installing a skill does not make its instructions trustworthy: review sources and referenced scripts before using them with an agent.

Development

go test ./...
go vet ./...
go run ./cmd/skills-manager --help
# Validate your separate skill repository:
go run ./cmd/skills-manager validate /path/to/team-skills

License

MIT; see LICENSE.