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 (project scope by default)
  • skillctl list --skills-dir <dir>
  • skillctl list -R <git-url>
  • skillctl list downloads [skill-name]
  • skillctl search --project|--global|--repo
• Installation and versioning:
  • skillctl install <skill-name> [-p github|agents|claude|copilot|<path>] [--force]
  • skillctl install <skill-name>@<version>
  • skillctl install -r <repo> <skill-name> [-v <version>] [--skill-project <project>] [-p <target>] [--force]
  • 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> [--project] [--repo <repo>] [--skill-project <project>]
  • skillctl update --all [--project] [--repo <repo>] [--skill-project <project>]
• Distribution:
  • skillctl push <skill-name> -R <remote-url>
  • skillctl push <skill-name> -r <repo-name>

Task-to-Command Quick Map

• User says "我想看看项目里都有什么 skill":
  • skillctl list
• User says "我只想看某个仓库的技能":
  • skillctl list --repo <repo-name>
  • skillctl search -r <repo-name> <keyword>
• User says "我要装指定版本":
  • skillctl list --versions <skill> -r <repo> [--skill-project <project>]
  • skillctl install <skill>@<version> -r <repo> [--skill-project <project>] -p <target>
• User says "批量更新":
  • skillctl outdated [--repo <repo>] [--skill-project <project>]
  • skillctl update --all [--repo <repo>] [--skill-project <project>]
• User says "发布到远端":
  • skillctl push <skill-name> -r <repo-name>
  • or skillctl push <skill-name> -R <remote-url>

Standard Playbooks

1) Install a Skill Safely (Project-first)

1. Confirm candidate exists:
   • skillctl search -r <repo> <skill-name>
2. If version-sensitive, list versions first:
   • skillctl list --versions <skill-name> -r <repo> [--skill-project <project>]
3. Install into explicit target:
   • skillctl install <skill-name> -r <repo> -p github
   • or skillctl install <skill-name>@<version> -r <repo> -p copilot
4. Validate result:
   • skillctl list

• skillctl list downloads <skill-name>

2) Update with Minimal Risk

1. Dry inspect:
   • skillctl outdated [--repo <repo>] [--skill-project <project>]
2. Update one skill first:
   • skillctl update <skill-name> [--repo <repo>] [--skill-project <project>]
3. Expand to all after confirmation:
   • skillctl update --all [--repo <repo>] [--skill-project <project>]
4. Re-check:
   • skillctl outdated

3) Publish and Version Tagging

1. Ensure SKILL.md has version and optional project.
2. Push:
   • skillctl push <skill-name> -r <repo-name>
3. Apply provider strategy:

• GitHub: direct push to default branch.
• GitLab: always use branch + MR flow.
• GitLab without GITLAB_TOKEN: branch push still works, and operator should follow the printed manual MR URL.

4. Verify tag policy in remote:
   • Preferred: <project>/<skill>@<version>
   • Compatible fallback: <skill>@<version>

Recommended Flag Conventions

• Always set repo explicitly in automation: -r <repo-name>.
• Always set target explicitly for installs: -p github|agents|claude|copilot.
• Use --skill-project whenever names may collide across projects.
• Use -d <project-dir> in scripts; do not rely on caller CWD.

Failure Patterns and Fixes

• Symptom: skill not found while install/update.
  • Check: skillctl list --repo, then skillctl install sync-repo <repo>.
  • Check naming: exact skill name and --skill-project.
• Symptom: multiple version tag matches.
  • Fix: add --skill-project <project> to disambiguate.
• Symptom: push fails with auth error.
  • GitHub: ensure GITHUB_TOKEN has repo scope.
  • GitLab: ensure GITLAB_TOKEN is set when MR auto-create is expected.
• Symptom: command appears to run in wrong location.
  • Fix: pass -d <project-dir> and -p <target> explicitly.

Output Contract for Agents

When this skill is used by an agent, responses should include:

1. Chosen command(s) with concrete flags.
2. Why this scope is selected (project/repo/remote).
3. What to verify after execution.
4. If command mutates state, include rollback/repair hint.

Suggested response shape:

Intent: <discover/install/update/push>
Command: <exact command>
Expected: <main outcome>
Verify: <follow-up command(s)>
If failed: <first troubleshooting step>

Guardrails

• Avoid deprecated local-first assumptions in plans and examples.
• Prefer project-first commands when user intent is ambiguous.
• Do not suggest push without -R or -r.
• For GitLab, explain that push always goes through branch + MR routing.
• Do not skip version discovery when user explicitly asks for a specific version line.

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: 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.

Example Scenarios

Scenario A: Install a skill for Copilot in current project

skillctl install docx -r ningskills -p copilot
skillctl list

Scenario B: Install exact version from specific project namespace

skillctl list --versions skillctl-operator-guide -r ningskills --skill-project skillctl
skillctl install skillctl-operator-guide@1.2.0 -r ningskills --skill-project skillctl -p github

Scenario C: Bulk update only one project namespace

skillctl outdated --skill-project ylapp
skillctl update --all --skill-project ylapp
skillctl outdated --skill-project ylapp

Safety and Validation

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

Regression Smoke Baseline

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