Author a Pixee CLI Resource Skill

Guided authoring of a new skill under skills/pixee-<noun>/SKILL.md. This repo distributes the skills that teach coding agents (Claude Code, Codex, others) to drive the pixee binary. Consistency across siblings is load-bearing for discoverability and the skills.sh install picker.

For general skill-writing fundamentals (what a SKILL.md is, progressive disclosure, how triggering works), invoke /plugin-dev:skill-development first if available. This skill layers pixee conventions on top; it does not repeat them. If that plugin is not installed, a one-paragraph refresher: a SKILL.md is a Markdown file with YAML frontmatter; the description field is how the model decides to invoke it, so it must enumerate concrete trigger phrases; keep the body scannable with clear H2 sections; front-load the most common use case.

Pixee context you must know

• Skills modularize around sub-commands. One skill per top-level pixee <subcommand> plus a single shared prerequisite skill (pixee-shared) that every domain skill references. This keeps each skill scoped to what an agent needs for one command group, and lets the install picker present a small menu of composable pieces.
• Install channel. Skills are fetched by agents via npx skills add pixee/pixee-cli --all (or the interactive picker without --all). A picker-breaking description silently drops the skill from the picker.
• Release cadence. Skill iteration is decoupled from pixee binary releases — revise a skill without waiting for the next CLI tag, and ship a subcommand now and its skill later if the surface isn't finalized.
• pixee-shared is a hard prerequisite for every domain skill. It covers global flags, exit codes, error rendering, and token security.
• pixee-api is the canonical HAL reference. Cross-reference it for discovery guidance. Never restate HAL. Never embed OpenAPI specs or long JSON schemas.

Before you author

The pixee binary on PATH is the authoritative source for what a skill should teach. Everything in the skill you write must be something you've seen the binary actually do.

1. Study the CLI by invoking it. Start with pixee --help for the top-level surface; then pixee <subcommand> --help and each nested pixee <subcommand> <verb> --help. Run realistic invocations end-to-end: try each flag, observe exit codes, run --output text and --output json against the same call to see the shape difference, and follow HAL links with pixee api <href> where the endpoint exposes them. Do not document flags or behaviors you haven't seen the binary produce.
2. Read two files in full: skills/pixee-shared/SKILL.md (every domain skill references it) and the single sibling closest to the new domain — the skill whose H1 shape you will copy. For a command-backed list/CRUD surface, pixee-repo (single verb) or pixee-workflow (subcommand-per-variant) is almost always the right reference.
3. Decide the slot. New pixee-<noun> skill versus extending an existing one. Prefer extension when the new surface is fewer than three subcommands and lives naturally inside an existing skill's H1 (e.g., a new pixee api --new-flag belongs in pixee-api, not a new skill).

Naming rules

• Slug is pixee-<noun> in kebab-case, where <noun> is a top-level subcommand or a cross-cutting concern (shared is the only current exception). Non-command cross-cutting slugs need discussion before landing.
• Directory layout: skills/pixee-<noun>/SKILL.md — single file. No references/ sidecar unless the skill exceeds ~150 lines; inline is the default.
• The H1 matches the command surface (# pixee workflow) or the skill name (# Pixee CLI — Shared Reference).

Frontmatter template

Copy this exactly and fill in the angle-bracket placeholders:

---
name: pixee-<noun>
description: "<verb-first, 100-130 chars, no colons, em-dashes, or parens>"
license: Apache-2.0
compatibility: Requires the pixee CLI binary on PATH
metadata:
  version: 1.0.0
  openclaw:
    category: "developer-tools"
    requires:
      bins:
        - pixee
    cliHelp: "pixee <subcommand> --help"
---

The description has a triple constraint, each one load-bearing:

• (a) Verb-first, bare infinitive. Existing descriptions start with Describe, Store, Send, List, List, create, and delete. Match the shape — this is what the skills.sh picker renders well.
• (b) Describes what the skill covers, not how it works. "List Pixee repositories and resolve names to UUIDs" is right. "Runs pixee repo list and does name resolution via the API" is wrong.
• (c) No colons, em-dashes, or parentheses. They break the skills.sh picker silently. Commit f0e73a3 (ISS-6922) rewrote all five existing descriptions for exactly this reason. Length: 100–130 chars.

version stays 1.0.0 until we agree to start bumping. Don't invent a scheme.

license is always Apache-2.0 — it matches skills/LICENSE, which covers the whole directory. compatibility is always Requires the pixee CLI binary on PATH unless the skill has a genuinely different runtime dependency. Both fields complete the Agent Skills spec (agentskills.io/specification); every skill in this repo carries them (ISS-8576).

cliHelp is pixee <subcommand> --help for command-backed skills; pixee --help for cross-cutting skills like pixee-shared.

Structural template

Don't try to invent shape. Open the closest sibling and follow its skeleton. Every skill in the set shares these invariants:

1. PREREQUISITE blockquote immediately after the frontmatter. Singular > **PREREQUISITE:** when only pixee-shared is referenced (see pixee-api, pixee-repo); plural > **PREREQUISITES:** when multiple are referenced (see pixee-workflow, which references shared + auth + repo).
2. Reference rule. Always reference pixee-shared first. Add pixee-auth when the subcommand authenticates (i.e., almost always, but only call it out when the skill's own content touches credential failure modes). Add pixee-repo when the skill uses the --repo name-or-UUID resolution protocol.
3. H2 per subcommand or topic. pixee-workflow shows the subcommand-per-H2 pattern; pixee-shared shows the topic-per-H2 pattern. Pick the one that matches your surface.
4. Bash examples with inline comments, realistic repo names (pixee/pixee-platform), and at least one example showing --json piped into jq.
5. Best practices tail. Short bulleted section covering scripting guidance: UUID vs name tradeoffs, pagination, mutually-exclusive flags, when to prefer the subcommand over the pixee api escape hatch.

Content doctrine

• Self-contained. Don't assume the agent read anything beyond pixee-shared.
• Cross-reference pixee-api for HAL. Never embed OpenAPI specs or long JSON schemas in the body.
• Mirror API field names in flag docs. Don't invent CLI aliases. If the API field is branch_pattern, the flag is --branch or --branch-pattern — not --branch-regex or --on-branch.
• Examples must work in both text and json output modes. Show the --json | jq path at least once.
• Audience is Claude Code and Codex (and future agents). Avoid Anthropic-specific phrasing ("ask Claude to…"). Write to "the agent."

After you author

1. Update README.md. Add a bullet under ## Coding agent plugin (in the npx skills fallback subsection) matching the shape of the existing bullets:

   - [`pixee-<noun>`](./skills/pixee-<noun>/SKILL.md) — <one-line description matching the frontmatter>.
   

2. License. The skills/ directory is Apache-2.0 via skills/LICENSE. No per-file header. skills/NOTICE stays untouched unless the new skill pulls in third-party attributions (unlikely for documentation).

3. Commit style. Follow recent history: short imperative + issue tag, e.g. Add pixee-scan skill (ISS-XXXX). Use a fresh issue number — ISS-6922 is closed.

4. Picker smoke test. Run npx skills add pixee/pixee-cli (no --all) and confirm the new entry appears in the interactive picker with its full description visible. If it's missing, the description has picker-breaking characters — fix before landing.

5. Plugin manifests. Two manifests both auto-discover skills from skills/*/SKILL.md — adding or removing a skill doesn't require touching either:

   • Root plugin.json — the Agent Plugins spec, read by VS Code and Cursor.
   • .claude-plugin/plugin.json and .claude-plugin/marketplace.json — Claude Code's format, also read by GitHub Copilot CLI and Codex CLI.

   Both version independently of any skill's metadata.version, starting at 1.0.0, and move together — they describe the same plugin. Bump them (semver, all three files in lockstep) only when the plugin's own identity changes — name, description, keywords, license, author, repository — not on every skill edit.

   marketplace.json's top-level name is pixee (the org), deliberately not pixee-cli (the repo/plugin) — this lets future Pixee plugins join the same marketplace without a rename. Never change it to match the repo name; that's not a bug to fix.

Updating an existing skill

Same rules, applied on the edit:

• Preserve the description's verb-first, picker-friendly shape on any rewrite. A rewrite that introduces a colon or em-dash is a picker regression, not a prose polish.
• Keep version decisions consistent across siblings. Don't bump one skill's version in isolation — the set moves together or stays.
• license and compatibility are constants (see Frontmatter template above) — an edit should never change them unless the skill's actual binary dependency changes.
• Don't diverge PREREQUISITE phrasing from the rest of the set in a single-skill edit. If the convention needs to change, update all five siblings in one commit.

Anti-patterns

• Emojis or Unicode punctuation in description — break the picker silently.
• Copy-pasting exit-code or global-flag content from pixee-shared instead of cross-referencing it.
• Hardcoded API paths or embedded OpenAPI fragments — violates HAL-first doctrine and dates fast.
• Anthropic-Claude-Code-specific phrasing. The skills serve Codex and others too.
• Per-file license headers. skills/LICENSE covers the directory.