cli: add --skill agent instructions

[desimone]

Summary

Agents using pomerium-cli currently have to rediscover its command contract or install a separate skill. Add a root-local --skill flag that prints an embedded Agent Skills-compatible SKILL.md verbatim to stdout.

Runtime --help remains the source of truth for commands and flags. The skill instructs agents to ignore route-provided connect_command text and construct TCP or UDP invocations from the structured type and from fields. The flag does not install files or add dependencies.

Representative output:

$ pomerium-cli --skill | sed -n '1,6p'
---
name: pomerium-cli
description: Use Pomerium CLI to discover accessible routes, open authenticated TCP or UDP tunnels, supply kubectl credentials, inspect CLI state, or retrieve a route authorization token. Use when a user mentions pomerium-cli or needs command-line access to a non-HTTP service protected by Pomerium.
---

# Pomerium CLI

Related issues

Fixes ENG-4291, which records Scott Hanselman's July 29, 2026 tweet proposing a CLI-native --skill command.

Testing

• go test -tags embed_pomerium ./cmd/pomerium-cli
• make build
• make test
• make lint

Checklist

• reference any related issues
• updated docs (SKILL.md is the user-facing documentation)
• updated unit tests
• updated UPGRADING.md (not applicable; no upgrade action required)
• add appropriate tag (improvement)
• ready for review

AI assistance

GPT-5.6 Codex drafted the implementation and PR body from Bobby DeSimone's product requirement; cross-model review tightened the route-command safety guidance.