agent-ctl 0.1.0

CLI for agent hub validation, index generation, and skill management
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# agentctl

CLI for agent hub validation, index generation, and skill management.
Implements the hub formats defined in [agent-foundation](https://github.com/geronimo-iia/agent-foundation).

## Install

**Homebrew** (macOS/Linux):
```bash
brew tap geronimo-iia/agent
brew install agentctl
```

**cargo-binstall** (installs pre-built binary):
```bash
cargo binstall agent-ctl
```

**cargo** (builds from source):
```bash
cargo install agent-ctl
```

**Binary download**: grab the latest release from [GitHub Releases](https://github.com/geronimo-iia/agentctl/releases).

## Quickstart

Validate a hub directory:
```bash
agentctl hub validate --type docs --path ./my-hub
agentctl hub validate --type skills --path ./my-skills
```

Generate `index.json`:
```bash
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)

```json
{
  "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"
    }
  ]
}
```

## CI Integration

Example GitHub Actions workflow for a docs or skills hub:

```yaml
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