Skip to content

SKILLS.MD

Latest commit

 

History

History
101 lines (79 loc) · 4.73 KB

SKILLS.MD

File metadata and controls

101 lines (79 loc) · 4.73 KB

MCP C++ SDK Skills

agents.md is the canonical policy file. This file turns those rules into repeatable execution skills for Codex, Windsurf, Cursor, VS Code, and Claude Code.

Load Order

  1. Read agents.md.
  2. Read SKILLS.MD.
  3. Select every matching skill before acting.
  4. If any command, test, build, access check, lint, doc check, or unrelated validation fails, stop and fix it immediately before continuing.

Skill: repo-governance

Use for every task.

  • Reuse include/mcp/ interfaces and shared transport/auth abstractions before adding parallel code paths.
  • Run architecture checks first. If architecture enforcement fails, all other work is blocked.
  • Keep SPDX headers, repository-relative File: paths, tests, and docs aligned with the change.
  • Never run builds, tests, or debug commands on the host.

Skill: docker-first-no-host-write

Use for build, test, debug, inspection, or automation work that executes code.

  • Linux and macOS commands use bash.
  • Windows commands use wsl -d Ubuntu -- bash -lc "..."
  • Build from repo context, then run from image-embedded source. Do not mount the repo into containers.
  • Do not use bind mounts, named volumes, docker cp, -o type=local, or any Docker pattern that writes back to the host.
  • Prefer --network none. If network or IPC is required, stop and get explicit human approval first.
# Linux/macOS
docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test .
docker run --rm --network none --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=1g \
  --entrypoint bash mcp-cpp-test \
  -lc "cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R '^Architecture' -VV --output-on-failure"
docker run --rm --network none --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=1g \
  --entrypoint bash mcp-cpp-test \
  -lc "cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure"

# Windows (PowerShell via WSL)
wsl -d Ubuntu -- bash -lc "cd /mnt/<drive>/<path-to-repo>/mcp-cpp && \
docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test ."
wsl -d Ubuntu -- bash -lc "docker run --rm --network none --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=1g \
  --entrypoint bash mcp-cpp-test \
  -lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R \"^Architecture\" -VV --output-on-failure'"
wsl -d Ubuntu -- bash -lc "docker run --rm --network none --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=1g \
  --entrypoint bash mcp-cpp-test \
  -lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure'"

Emit results to stdout or stderr only. Do not export artifacts back to the host.

Skill: failure-first-remediation

Use whenever anything fails, including failures that look unrelated to the active task.

  • Treat access-denied errors, safe-directory errors, failing unrelated tests, header drift, doc drift, lint issues, and Docker misconfiguration as blocking failures.
  • Fix the failure immediately, rerun the failed gate, then rerun the next broader gate that depends on it.
  • Do not scope a failure away as "out of band" or "not part of this task."

Skill: sequential-verification

Use for auth switching, remote changes, repo creation, branch tracking changes, commits, pushes, and permission or remote failures.

  • Make one stateful change at a time.
  • Do not parallelize a state-changing command with its verification command.
  • After each auth, remote, or repo-target change, verify immediately with direct checks such as gh api user --jq .login, gh auth status, git remote -v, git branch -vv, and gh repo view owner/repo.
  • Keep service auth identity separate from commit author identity; verify both when the requested identity matters.
  • Do not blame remotes, permissions, or provider state until active account, target repo existence, remote URL, and branch tracking have been verified in order.
  • If verification fails, stop, isolate the mismatch, fix the exact prerequisite, rerun the failed verification, and only then continue.

Skill: review-and-delivery

Use when reviewing or finalizing work.

  • Findings come first in reviews, with file and line references.
  • For implementation work, verify the architecture gate before broader test suites.
  • If repository rules and tool rules conflict, obey the stricter rule and update the enforcement docs in the same change.