agentctl is a cross-platform Go CLI for syncing AI agent and skill definitions from a Git-based registry into local projects.

It supports:

• opencode target (.opencode/...)
• Claude Code target (.claude/... + CLAUDE.md)

All remote operations are done through the local git binary (SSH/HTTPS auth handled by your existing Git setup).

git clone <this-repo>
cd agentctl
go build ./cmd/agentctl

Optional: install into your GOPATH/bin

go install ./cmd/agentctl

agentctl init --path ./my-agent-registry

Creates:

my-agent-registry/
  agents/
    example-agent.md
  skills/
    example-skill/
      SKILL.md
  registry.yaml
  README.md
  .gitignore

cd /path/to/your/project
agentctl sync \
  --repo git@github.com:company/agent-registry.git \
  --ref v1.2.0 \
  --agents architect,builder \
  --skills golang,kubernetes \
  --target opencode

Interactive selection is available when --agents and --skills are omitted (TTY required).

agentctl status

agentctl list --repo git@github.com:company/agent-registry.git --ref main
agentctl list --repo git@github.com:company/agent-registry.git --ref main --format json

agentctl update --ref v1.3.0
agentctl update --add-skills terraform
agentctl update --remove-agents tester

agentctl version
agentctl version --format json

agentctl completion zsh
agentctl completion bash
agentctl completion fish
agentctl completion powershell

Registry repository layout:

agents/
  architect.md
  builder.md
skills/
  golang/
    SKILL.md
  kubernetes/
    SKILL.md
registry.yaml   # optional

registry.yaml is optional. If missing, agentctl discovers:

• agents from agents/*.md
• skills from skills/*/SKILL.md

registry.yaml supports both list-style and map-style entries, with optional metadata (description, tags, model, permission, tools, rules, compat).

Uniform agent config fields:

• model: string
• permission: string
• tools: []string
• rules: [] command-level approvals (canonical allow/ask/deny), e.g.:

rules:
  - tool: bash
    command: "git status*"
    decision: allow
  - tool: bash
    command: "git push*"
    decision: ask

• compat.on_lossy: warn|strict (default warn) for targets that cannot represent all metadata (e.g. command-level bash rules in claude-code).

This is the expected structure for the agent registry repository that agentctl reads from:

agents/
  architect.md
  builder.md
  tester.md
  security-auditor.md
  ...
skills/
  golang/
    SKILL.md
    templates/
      ...
  kubernetes/
    SKILL.md
  terraform/
    SKILL.md
  ...
registry.yaml   # optional metadata

If registry.yaml is missing, agentctl falls back to directory discovery.

• Go 1.22+
• Git on PATH

# run tests
go test ./...

# build binary
go build ./cmd/agentctl

# run CLI without installing
go run ./cmd/agentctl --help

1. Write/adjust tests first (TDD style).
2. Implement smallest change to pass tests.
3. Refactor while keeping tests green.
4. Run go test ./... before commit.

go build \
  -ldflags "-X main.version=dev -X main.commit=$(git rev-parse --short HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  ./cmd/agentctl

Each sync writes .agentctl.lock.yaml in the project root, capturing source repo/ref/SHA, selected agents/skills, target, and sync time. agentctl update uses this file to perform non-interactive updates.