audit-skills

Name: audit-skills
Author: pixee

31stars12forks

How to install audit-skills?

pixee/pixee-cli/audit-skills

$npx -y skills add pixee/pixee-cli --skill audit-skills

Installs into the current project.

Summary

Detects and closes drift between the latest released Pixee CLI surface and the published skills/pixee-* skills on origin/main. Trigger after a new pixee release, on a /audit-skills request, or when the contributor asks 'are the skills up to date?', 'is there a missing pixee

Files · 1

View on GitHub

SKILL.md

1	# Audit Pixee CLI Skills for Drift
2
3	A maintenance workflow that compares the live `pixee` binary on PATH (the release the contributor actually shipped) against the *published `skills/pixee-/SKILL.md` on `origin/main`** (what users actually pull via `npx skills add pixee/pixee-cli`), then closes any gaps through DevRev and `/dev-workflow:implement-issue`.
4
5	The skills shipped from this repo (`pixee/pixee-cli`) teach coding agents to drive `pixee`. Whenever a new subcommand, verb, or flag lands in the CLI without a corresponding skill update, agents silently fall back to guessing — that is what this skill exists to prevent.
6
7	## When to run
8
9	- Right after a new `pixee` release — the canonical trigger, paired with `--headless` if you want a hands-off run.
10	- Ad-hoc when a contributor suspects drift after merging a `pixee-cli-private` PR that adds a subcommand or flag.
11	- As a scheduled CI job that runs the audit phase only (no remediation) and posts the report somewhere.
12
13	`pixee` must be on `PATH` and must point at the release the contributor wants to audit. If `pixee --version` does not match the latest tag on `pixee/pixee-cli`, stop and ask the contributor whether to upgrade first (skip the prompt under `--headless` — note the version mismatch in the report and proceed).
14
15	## Hard rules
16
17	1. Map skills to subcommands by `cliHelp`, not by slug. The skill that covers `pixee organization preferences` is called `pixee-preferences`, not `pixee-organization`. Skill slugs are stable across renames; CLI subcommand names evolve, so joining by slug silently diverges as the surface moves. Read each skill's frontmatter `cliHelp` field (`cliHelp: "pixee <subcommand> --help"`) to learn what it covers; only use slug as a tiebreaker for cross-cutting skills like `pixee-shared`.
18	2. Audit first, remediate second. Never file a DevRev issue or invoke `/dev-workflow:implement-issue` before producing the drift report and getting approval. Under `--headless` the report is the approval — file issues immediately after producing it.
19	3. One issue per gap. Each missing skill, each orphaned skill, each material flag drift becomes its own DevRev issue in part `CAPL-44`.
20	4. `pixee --help` is the binary's source of truth. Skill content is correct when it matches the help output of the binary on `PATH`.
21	5. Don't invent skills. When a CLI surface is small and naturally belongs inside an existing skill, file an issue to extend the sibling, not to add a new `pixee-<noun>` skill. See `.claude/skills/add-resource-skill/SKILL.md` for the slot-decision rule.
22
23	## Headless mode
24
25	Pass `--headless` for unattended runs (post-release CI, scheduled cron). The skill behaves the same except:
26
27	- No `AskUserQuestion` calls. Decisions that would normally prompt the contributor (e.g., "is this surface big enough to warrant its own skill?") default to the most defensible choice; the choice is recorded explicitly in the DevRev issue body under an `Assumptions:` bullet so the PR reviewer can correct it.
28	- No "confirm to remediate" stop. The audit phase runs, the report is produced, and DevRev issues + `/implement-issue` runs proceed without waiting for approval.
29	- Notification at the end. Notify the user with the issue IDs that were filed (e.g. "audit-skills: filed N issues for pixee `<version>`: ISS-AAAA, ISS-BBBB, ...").
30	- Version mismatch is a warning, not a stop. If `pixee --version` lags `origin/main`'s latest tag, note it in the report header and proceed. A human can decide whether to act on the report.
31
32	Interactive mode is the default. When in doubt, ask.
33
34	## Workflow
35
36	Open these as `TaskCreate` tasks at the start of the run so the assumption-verification steps in the remediate phase don't get skipped under pressure:
37
38	1. Resolve binary version + `origin/main` SHA
39	2. Enumerate the CLI surface
40	3. Enumerate the published skills (from `origin/main`)
41	4. Compare and classify each gap
42	5. Produce the drift report
43	6. (Interactive) Stop for approval. (Headless) Skip.
44	7. File DevRev issues
45	8. Run `/dev-workflow:implement-issue` per issue
46	9. (Headless) Notify
47
48	### Step 1. Resolve binary version and the published skill set
49
50	Pin both ends of the comparison and put them in the report header.
51
52	```bash
53	pixee --ver

People who liked this also viewed

6 picks

Type

audit-skills

31stars12forks

View on GitHub

How to install audit-skills?

pixee/pixee-cli/audit-skills

$npx -y skills add pixee/pixee-cli --skill audit-skills

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Audit Pixee CLI Skills for Drift
2
3	A maintenance workflow that compares the live `pixee` binary on PATH (the release the contributor actually shipped) against the *published `skills/pixee-/SKILL.md` on `origin/main`** (what users actually pull via `npx skills add pixee/pixee-cli`), then closes any gaps through DevRev and `/dev-workflow:implement-issue`.
4
5	The skills shipped from this repo (`pixee/pixee-cli`) teach coding agents to drive `pixee`. Whenever a new subcommand, verb, or flag lands in the CLI without a corresponding skill update, agents silently fall back to guessing — that is what this skill exists to prevent.
6
7	## When to run
8
9	- Right after a new `pixee` release — the canonical trigger, paired with `--headless` if you want a hands-off run.
10	- Ad-hoc when a contributor suspects drift after merging a `pixee-cli-private` PR that adds a subcommand or flag.
11	- As a scheduled CI job that runs the audit phase only (no remediation) and posts the report somewhere.
12
13	`pixee` must be on `PATH` and must point at the release the contributor wants to audit. If `pixee --version` does not match the latest tag on `pixee/pixee-cli`, stop and ask the contributor whether to upgrade first (skip the prompt under `--headless` — note the version mismatch in the report and proceed).
14
15	## Hard rules
16
17	1. Map skills to subcommands by `cliHelp`, not by slug. The skill that covers `pixee organization preferences` is called `pixee-preferences`, not `pixee-organization`. Skill slugs are stable across renames; CLI subcommand names evolve, so joining by slug silently diverges as the surface moves. Read each skill's frontmatter `cliHelp` field (`cliHelp: "pixee <subcommand> --help"`) to learn what it covers; only use slug as a tiebreaker for cross-cutting skills like `pixee-shared`.
18	2. Audit first, remediate second. Never file a DevRev issue or invoke `/dev-workflow:implement-issue` before producing the drift report and getting approval. Under `--headless` the report is the approval — file issues immediately after producing it.
19	3. One issue per gap. Each missing skill, each orphaned skill, each material flag drift becomes its own DevRev issue in part `CAPL-44`.
20	4. `pixee --help` is the binary's source of truth. Skill content is correct when it matches the help output of the binary on `PATH`.
21	5. Don't invent skills. When a CLI surface is small and naturally belongs inside an existing skill, file an issue to extend the sibling, not to add a new `pixee-<noun>` skill. See `.claude/skills/add-resource-skill/SKILL.md` for the slot-decision rule.
22
23	## Headless mode
24
25	Pass `--headless` for unattended runs (post-release CI, scheduled cron). The skill behaves the same except:
26
27	- No `AskUserQuestion` calls. Decisions that would normally prompt the contributor (e.g., "is this surface big enough to warrant its own skill?") default to the most defensible choice; the choice is recorded explicitly in the DevRev issue body under an `Assumptions:` bullet so the PR reviewer can correct it.
28	- No "confirm to remediate" stop. The audit phase runs, the report is produced, and DevRev issues + `/implement-issue` runs proceed without waiting for approval.
29	- Notification at the end. Notify the user with the issue IDs that were filed (e.g. "audit-skills: filed N issues for pixee `<version>`: ISS-AAAA, ISS-BBBB, ...").
30	- Version mismatch is a warning, not a stop. If `pixee --version` lags `origin/main`'s latest tag, note it in the report header and proceed. A human can decide whether to act on the report.
31
32	Interactive mode is the default. When in doubt, ask.
33
34	## Workflow
35
36	Open these as `TaskCreate` tasks at the start of the run so the assumption-verification steps in the remediate phase don't get skipped under pressure:
37
38	1. Resolve binary version + `origin/main` SHA
39	2. Enumerate the CLI surface
40	3. Enumerate the published skills (from `origin/main`)
41	4. Compare and classify each gap
42	5. Produce the drift report
43	6. (Interactive) Stop for approval. (Headless) Skip.
44	7. File DevRev issues
45	8. Run `/dev-workflow:implement-issue` per issue
46	9. (Headless) Notify
47
48	### Step 1. Resolve binary version and the published skill set
49
50	Pin both ends of the comparison and put them in the report header.
51
52	```bash
53	pixee --ver

People who liked this also viewed

6 picks

Type