vcpkg Registry Maintenance

Assist with maintaining a custom vcpkg registry overlay. This skill guides GitHub Copilot through port creation, updates, version baseline management, and troubleshooting for vcpkg package management.

What This Skill Does

This skill enables systematic maintenance of vcpkg registry ports following established workflows for:

Instructions for AI Agent

Core Workflows

#### 1. Creating a New Port

**Objective:** Add a new vcpkg port to the registry following vcpkg best practices.

**Process:**

1. **Search phase** (`/search-port`): Check if port already exists in vcpkg public registry or this overlay

2. **Creation phase** (`/create-port`):

- Research upstream project (GitHub repo, releases, build system)

- Create port directory structure under `ports/[package-name]/`

- Write `vcpkg.json` manifest with dependencies and features

- Write `portfile.cmake` with download, extract, build, and install steps

- Calculate SHA512 checksums for source archives

- Follow patterns in `docs/guide-create-port.md`, `docs/guide-create-port-build.md`, `docs/guide-create-port-download.md`

3. **Installation phase** (`/install-port`): Test port installation with `vcpkg install --overlay-ports=./ports`

4. **Review phase** (`/review-port`): Verify manifest correctness, build logic, and installation results

**Key considerations:**

#### 2. Updating an Existing Port

**Objective:** Update port to newer upstream version or adjust build configuration.

**Process:**

1. **Upstream check** (`/check-port-upstream`): Compare current version with upstream releases

2. **Update phase** (`/update-port`):

- Modify `vcpkg.json` version fields

- Update `portfile.cmake` download URLs and SHA512 checksums

- Adjust build steps if upstream changed build system

- Follow procedures in `docs/guide-update-port.md`

3. **Installation phase** (`/install-port`): Test updated port

4. **Review phase** (`/review-port`): Validate changes and installation

**Key considerations:**

#### 3. Updating Version Baseline

**Objective:** Synchronize `versions/` directory JSON files after port changes.

**Process:**

1. Run `/update-version-baseline` prompt

2. Execute `scripts/registry-add-version.ps1` helper script

3. Verify `versions/baseline.json` and `versions/[first-letter]-/[package-name].json` updated correctly

4. Follow procedures in `docs/guide-update-version-baseline.md`

**Key considerations:**

#### 4. Troubleshooting Port Issues

**Objective:** Diagnose and resolve port installation or build failures.

**Process:**

1. **Environment check** (`/check-environment`): Verify vcpkg installation, compiler, CMake version

2. **Installation test** (`/install-port`): Run installation with verbose output

3. **Review logs** (`/review-port`): Analyze build logs, identify failure patterns

4. **Consult guide**: Reference `docs/troubleshooting.md` for common issues

**Common issues addressed:**

Documentation Hierarchy

**When assisting, reference documentation in this order:**

1. **Setup/environment:** `README.md`, `docs/references.md`

2. **Task-specific guides:**

- Port creation: `docs/guide-create-port.md`, `docs/guide-create-port-build.md`, `docs/guide-create-port-download.md`

- Port updates: `docs/guide-update-port.md`

- Version baseline: `docs/guide-update-version-baseline.md`

- Problems: `docs/troubleshooting.md`

3. **External resources:** `docs/references.md`

Command Patterns

**Overlay usage (always explicit):**

```bash

vcpkg install <port> --overlay-ports=./ports --overlay-triplets=./triplets

vcpkg x-update-baseline --add-initial-baseline

```

**Helper scripts:**

```powershell

./scripts/registry-add-version.ps1 <port-name>

./scripts/registry-format.ps1

```

Safety Constraints

Output Format

Report task results with structured indicators:

Include:

Examples

**Creating a new port:**

```

User: "Create a port for libfoo version 2.1.0"

Agent:

1. ✅ Searched vcpkg registry — libfoo not found

2. ✅ Created ports/libfoo/vcpkg.json and portfile.cmake

3. ✅ Calculated SHA512 for v2.1.0 archive

4. ✅ Test install succeeded on x64-windows

5. ⚠️ Recommendation: Test on linux triplet before merging

```

**Updating version baseline:**

```

User: "Update baseline after modifying libbar"

Agent:

1. ✅ Ran scripts/registry-add-version.ps1 libbar

2. ✅ Updated versions/baseline.json

3. ✅ Updated versions/l-/libbar.json with new version entry

```

Constraints