agentctl

CLI for agent hub validation, index generation, and skill management. Implements the hub formats defined in agent-foundation.

Install

Homebrew (macOS/Linux):

brew tap geronimo-iia/agent
brew install agentctl

cargo-binstall (installs pre-built binary):

cargo binstall agent-ctl

cargo (builds from source):

cargo install agent-ctl

Binary download: grab the latest release from GitHub Releases.

Quickstart

Validate a hub directory:

agentctl hub validate --type docs --path ./my-hub
agentctl hub validate --type skills --path ./my-skills

Generate index.json:

agentctl hub generate --type docs --path ./my-hub --output index.json
agentctl hub generate --type skills --path ./my-skills --hub-id my-hub --output index.json

Usage

agentctl --help
agentctl hub --help

Validation output

On success:

✓ Validation passed

On failure (exit code 1):

  ✗ skills/my-skill/SKILL.md:1: missing required field: name
  ✗ skills/my-skill/SKILL.md:1: missing required field: description
✗ Validation failed (2 error(s))

Generated index.json (skills)

{
  "hub_id": "my-hub",
  "generated_at": "2026-07-14T10:00:00Z",
  "skills": [
    {
      "name": "python-scaffold",
      "description": "Scaffold a Python project",
      "path": "python-scaffold",
      "commit_hash": "abc1234"
    }
  ]
}

Hub Registry

agentctl hub add --type skills agent-foundation https://raw.githubusercontent.com/geronimo-iia/agent-foundation/main/skills/index.json
agentctl hub add --type docs agent-foundation https://raw.githubusercontent.com/geronimo-iia/agent-foundation/main/docs/index.json
agentctl hub list
agentctl hub disable agent-foundation
agentctl hub enable agent-foundation
agentctl hub remove agent-foundation
agentctl hub refresh agent-foundation   # force-refresh one hub
agentctl hub refresh                    # refresh all enabled hubs

agentctl.toml

Optional file at the hub root. When present, values are used as defaults; CLI flags always take precedence.

[hub]
id = "agent-foundation"  # overrides --hub-id on generate

[generate]
# Replaces the default exclusion list when present.
# Matched case-insensitively against filename only (not path).
# Supports a single * wildcard anywhere in the pattern.
ignore = [
  "README.md",
  "CHANGELOG.md",
  "CONTRIBUTING.md",
  "ARCHIVED.md",
  "draft-*.md",
]

When agentctl.toml is absent or has no [generate] ignore key, the default exclusions apply: README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE*, ARCHIVED.md.

See docs/hub-config.md for full details including cache layout and TTL behaviour.

CI Integration

Example GitHub Actions workflow for a docs or skills hub:

name: Publish Index

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Install agentctl
        run: |
          curl -sSL https://github.com/geronimo-iia/agentctl/releases/latest/download/x86_64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/bin

      - name: Validate
        run: agentctl hub validate --type docs --path .

      - name: Generate index.json
        run: agentctl hub generate --type docs --path . --output index.json

      - name: Commit index.json
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add index.json
          git diff --staged --quiet || git commit -m "chore: regenerate index.json [skip ci]"
          git push

Replace --type docs with --type skills for a skills hub.

License

MIT OR Apache-2.0

agent-ctl 0.2.0