iagent-skill-hub

Requires Python 3.11 or newer. The CLI uses only the Python standard library at runtime.

Install from this repository:

python3.11 -m pip install ./cli
iagent-skill-hub --help

Or run without installing:

PYTHONPATH=cli python3.11 -m iagent_skill_hub.cli --help

The default API is https://skillshub.kiwilightyear.com/api/v1. Set IAGENT_SKILL_HUB_API_BASE or pass --api-base before the command to use another API. Protected commands use a Pearl access token from IAGENT_SKILL_HUB_TOKEN or --token. The previous MUSHROOM_HUB_* environment variables also work. The backend accepts the token in Authorization: Bearer ...; a browser GitHub session cookie cannot be used as a CLI token.

export IAGENT_SKILL_HUB_API_BASE=http://127.0.0.1:8000/api/v1
export IAGENT_SKILL_HUB_TOKEN=<your-pearl-access-token>

iagent-skill-hub list --query markdown --sort-by stars
iagent-skill-hub info example-skill
iagent-skill-hub files example-skill
iagent-skill-hub versions example-skill
iagent-skill-hub cat example-skill SKILL.md
iagent-skill-hub download example-skill --version 1.0.0 --output example.zip
iagent-skill-hub install example-skill
iagent-skill-hub install example-skill --dir ./skills/example-skill --force
iagent-skill-hub uninstall example-skill

iagent-skill-hub publish example-skill --dir ./my-skill --name "Example Skill" \
  --version 1.0.0 --changelog "Initial release" --tag tools
iagent-skill-hub edit example-skill --dir ./my-skill --name "Example Skill" \
  --version 1.1.0 --changelog "Add examples"
iagent-skill-hub edit example-skill --name "Example Skill" \
  --version 1.1.0 --changelog "Update metadata"
iagent-skill-hub delete example-skill

iagent-skill-hub stars example-skill
iagent-skill-hub star example-skill
iagent-skill-hub unstar example-skill
iagent-skill-hub starred
iagent-skill-hub comments example-skill
iagent-skill-hub comment example-skill "Helpful skill"

publish uploads every file below --dir through the backend's presigned URL API, then publishes the manifest. edit with --dir replaces the version's file set; omitting --dir keeps the existing files. The directory must contain a nonempty SKILL.md. install extracts an archive under ~/.mushroom-agent-hub/skills/<slug> by default and refuses to replace an existing directory unless --force is given.

Run tests with python3.11 -m unittest discover -s cli/tests -v from the repository root.

Publish to the internal Python package registry

To publish directly from your machine, use the local script from the repository root (it also works from another directory):

./cli/publish-internal.sh --dry-run
./cli/publish-internal.sh

The script needs uv, runs the CLI tests, builds an isolated wheel and source archive, checks them with Twine, and then uploads them to the internal registry. Twine prompts for the internal account password unless TWINE_PASSWORD is already set. Change version in cli/pyproject.toml before publishing a new release.

The GitHub Actions workflow .github/workflows/publish-python-cli-to-internal-pypi.yml builds, tests, checks, and uploads the package to https://pypi.kiwilightyear.com/internal/prod/ when a tag such as iagent-skill-hub-v0.1.0 is pushed. The tag version must match cli/pyproject.toml. Increment the version for each new release.

Before releasing, create a GitHub environment named internal-pypi and add its secret INTERNAL_PYPI_PASSWORD with the password for the internal account. The workflow passes that account and secret separately to the upload action; do not put credentials in the repository URL. The runner must be able to reach the internal registry.

For installation after release, use the registry's Simple API index URL with pip or uv. That URL may differ from the upload endpoint above; get the install URL and read credentials from your registry administrator. Keep credentials out of the command history where possible.

After merging the package and workflow, publish a matching tag:

git tag iagent-skill-hub-v0.1.0
git push origin iagent-skill-hub-v0.1.0

Publish to public PyPI from your machine

Use a PyPI API token for the iagent-skill-hub project. For the first release, the token needs permission to create the project. The script prompts for the token unless TWINE_PASSWORD is set; do not put it in the repository or a command-line argument.

./cli/publish-pypi.sh --dry-run
./cli/publish-pypi.sh

This uploads to https://upload.pypi.org/legacy/ with username __token__. After publishing, install with python3.11 -m pip install iagent-skill-hub. Increment cli/pyproject.toml's version before publishing another release.