# Agentctl

> Validate and generate index.json for agent skill and doc hubs, manage hub registry, install/update/remove skills, and manage local agentctl config using agentctl. Use when maintaining hub directories, publishing hub indexes, managing installed skills, or configuring agentctl.

- Skill: `geronimo-iia/agentctl` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add geronimo-iia/agentctl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/geronimo-iia/agentctl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: geronimo-iia (https://skillmd.com/u/geronimo-iia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/geronimo-iia/agentctl

---


# agentctl Hub & Skill Management

Validates hub directories, generates `index.json`, manages hub registry, installs/updates/removes skills, and manages local config using [agentctl](https://github.com/geronimo-iia/agentctl).

## Install

```sh
brew tap geronimo-iia/agent && brew install agentctl
# or
cargo install agent-ctl
```

## Hub commands

```sh
# Validate
agentctl hub validate --type skills --path ./my-skills
agentctl hub validate --type docs --path ./my-docs

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

# Registry
agentctl hub add --type skills agent-skills https://raw.githubusercontent.com/org/repo/main/index.json --git-url https://github.com/org/repo
agentctl hub list
agentctl hub enable <id> / hub disable <id> / hub remove <id>
agentctl hub refresh [<id>] [--force]    # --force bypasses cache
```

## Skill commands

```sh
agentctl skill install <name> [--hub <id>] [--mode <mode>]
agentctl skill list
agentctl skill remove <name> --hub <id>
agentctl skill update [<name>] [--force]
agentctl skill export > skills.lock.json    # backup/share installations
```

**Global flags**: `--quiet` / `-q`, `--yes` / `-y`

## Config commands

```sh
agentctl config init          # create default ~/.agentctl/config.json
agentctl config show          # print full config
agentctl config path          # print config file path
agentctl config get skills_root
agentctl config set skills_root ~/.agent/skills
```

## CI integration

```yaml
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 skills --path .

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

      - name: Commit index.json
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        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
```

## Skills hub rules

- Each skill in its own directory with a `SKILL.md` file
- Required frontmatter fields: `name`, `description`
- Flat hierarchy — no nested skill directories
- Hidden directories (`.git`) are ignored

## Docs hub rules

- Required frontmatter fields: `title`, `summary`, `status`, `last_updated`, `read_when`
- `read_when` must be a non-empty list

## Hub configuration (agentctl.toml)

```toml
[hub]
id = "my-hub"

[generate]
ignore = [
  "README.md",           # filename patterns
  "draft-*.md",          # filename wildcards
  "rules/templates/",    # directory patterns (v0.4.1+)
  "docs/private/*.md",   # path wildcards (v0.4.1+)
]
```

**Enhanced ignore patterns** (v0.4.1+): Support for directory patterns ending with `/` and path wildcards for more precise file exclusion during hub validation and generation.