skillctl-operator-guide

Use this skill when the user asks how to use this repository's CLI tool skillctl, or requests command planning/execution for skill lifecycle management.

Capability Map

• Repository management:
  • skillctl add -r <url> [--repo-name --repo-default --repo-priority]
  • skillctl list --repo [repo-name]
  • skillctl install sync-repo [repo-name]
  • skillctl install default-repo <repo-name>
  • skillctl remove --repo <repo-name>
• Discovery and inventory:
  • skillctl list
  • skillctl list --project
  • skillctl list --skills-dir <dir>
  • skillctl list -R <git-url>
  • skillctl search --local|--project|--global|--repo
  • skillctl status
  • skillctl status downloads [skill-name]
• Installation and versioning:
  • skillctl install <skill-name>
  • skillctl install <skill-name>@<version>
  • skillctl install -r <repo> <skill-name> [-v <version>] [--skill-project <project>]
  • skillctl list --versions <skill-name> [--repo <repo>] [--skill-project <project>]
• Update lifecycle:
  • skillctl outdated [skill-name] [--repo <repo>] [--skill-project <project>]
  • skillctl update <skill-name> [--repo <repo>] [--skill-project <project>]
  • skillctl update --all [--local|--project] [--repo <repo>] [--skill-project <project>]
• Distribution:
  • skillctl push <skill-name>
  • skillctl push <skill-name> -r <repo-name>
  • skillctl push <skill-name> -R <remote-url>

Version Tag Rules

• Preferred namespaced tag: <project>/<skill>@<version>
• Legacy tag: <skill>@<version>
• If multiple projects publish same skill/version, require --skill-project for disambiguation.

Agent Decision Guide

1. Identify intent: discover / install / update / publish / clean.
2. Determine scope: local / project / repo / remote URL.
3. If version-sensitive:
   • list versions first,
   • pick project scope when ambiguous,
   • install with <name>@<version> or -v.
4. Before mass changes:
   • run skillctl outdated,
   • then run skillctl update --all with filters.
5. For publish workflows:
   • ensure skill metadata includes version and optional project,
   • push and verify tag strategy.

Safety and Validation

• Prefer read-only checks first: list, search, status, outdated.
• For mutating commands (add, install, update, push, remove), show planned command before execution.
• After command refactors, run smoke tests and go test ./....

GitLab MR Note

• skillctl push <skill-name> -r <repo-name> on GitLab only auto-creates a merge request when GITLAB_TOKEN is set.
• Without GITLAB_TOKEN, skillctl will still push the branch and tags successfully, but MR creation must be done manually via the printed URL.
• Recommended before push (Vault -> verify scopes -> cache capability):

$env:GITLAB_BASE_URL="https://gitlab.com"

# 1) Get token from Vault
$token = vault kv get -field=token agent-token/gitlab
if ([string]::IsNullOrWhiteSpace($token)) {
  throw "Failed to get GitLab token from Vault path: agent-token/gitlab"
}
$env:GITLAB_TOKEN = $token

# 2) Validate token and inspect scopes/capabilities
$headers = @{ "PRIVATE-TOKEN" = $token }
$self = Invoke-RestMethod -Method Get -Uri "$env:GITLAB_BASE_URL/api/v4/personal_access_tokens/self" -Headers $headers
Write-Host ("Token name: {0}" -f $self.name)
Write-Host ("Token scopes: {0}" -f ($self.scopes -join ", "))

# 3) Optional fallback check for environments where PAT self endpoint is restricted
if (-not $self -or -not $self.scopes) {
  $user = Invoke-RestMethod -Method Get -Uri "$env:GITLAB_BASE_URL/api/v4/user" -Headers $headers
  Write-Host ("Authenticated as: {0} ({1})" -f $user.username, $user.name)
}

# 4) Use token for push (MR auto-create requires api scope)
skillctl push <skill-name> -r <repo-name>

• Scope requirement for MR auto-create: token should include api scope.
• Memory rule: persist only capability snapshot, never the raw token.
• Suggested memory record path: /memories/repo/gitlab-token-capabilities.md.
• Suggested memory content example:

- Source: vault kv get -field=token agent-token/gitlab
- Verified At: 2026-04-29
- GitLab Base URL: https://gitlab.com
- Scopes: api, read_user
- Can Auto Create MR: yes

Regression Smoke Baseline

go test ./...
go run . -h
go run . add -h
go run . install -h
go run . list -h
go run . outdated -h
go run . push -h
go run . remove -h
go run . search -h
go run . status -h
go run . update -h