Metadata-Version: 2.5
Name: abvx-agent-skills
Version: 0.15.0
Summary: Small, reviewable, validation-gated agent skills for Codex-style project work.
Project-URL: Homepage, https://github.com/markoblogo/abvx-agent-skills
Project-URL: Repository, https://github.com/markoblogo/abvx-agent-skills
Project-URL: Issues, https://github.com/markoblogo/abvx-agent-skills/issues
Author: markoblogo
License-Expression: MIT
License-File: LICENSE
Keywords: agents,codex,llm,prompts,skills
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# ABVX Agent Skills

<p>
  <img src="assets/skillslogo.png" alt="ABVX Agent Skills logo" width="1536" height="1024">
</p>

Small, reviewable, validation-gated agent skills for Codex-style project work.

[![Validate](https://github.com/markoblogo/abvx-agent-skills/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/markoblogo/abvx-agent-skills/actions/workflows/validate.yml)
[![Security Audit](https://github.com/markoblogo/abvx-agent-skills/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://github.com/markoblogo/abvx-agent-skills/actions/workflows/security-audit.yml)
[![PyPI version](https://img.shields.io/pypi/v/abvx-agent-skills.svg?cacheSeconds=300)](https://pypi.org/project/abvx-agent-skills/)
![Catalog live](https://img.shields.io/badge/catalog-live-3b82f6)
![gh skill ready](https://img.shields.io/badge/gh%20skill-ready-111827)

ABVX Agent Skills is a small, auditable skillpack for coding agents that helps them write smaller diffs, debug from evidence, compact noisy shell output, and verify work before saying done. The proof-first pack keeps release, browser, locale, visual, device-boundary, and human-gated claims separate so an agent does not turn partial evidence into a confident public status.

These are not prompt dumps. They are compact `SKILL.md` workflows with clear triggers, attribution, risk notes, and validation. They are portable, versioned agent capabilities meant to be previewed, inspected, and loaded on demand through the Agent Skills progressive-disclosure model.

They also are not a replacement for MCP or CLI tools. In the ABVX stack, MCP is the access layer for external services, CLI is the execution layer for deterministic work, and skills are the discipline layer: they decide when to use MCP, when to use CLI, which checks are mandatory, and when a repeated workflow should become a reusable gate.

## Try One Skill In 2 Minutes

Preview before installing:

```bash
gh skill preview markoblogo/abvx-agent-skills minimal-diff-builder
```

Install one skill:

```bash
gh skill install markoblogo/abvx-agent-skills minimal-diff-builder --agent codex --scope user
```

Then ask your coding agent:

```text
Use minimal-diff-builder. Implement the smallest correct fix for this issue.
```

## Three Measured Demos

| Job | Skill | Evidence |
|---|---|---|
| Keep a bug fix small | `minimal-diff-builder` | [Correctness and changed lines](docs/demos/minimal-diff-builder.md) |
| Control exploration cost | `token-efficient-execution` | [Token usage and correct answers](docs/demos/token-economy.md) |
| Check whether a release is proven | `public-release-verification` | [Missing evidence and false live claims](docs/demos/public-release-verification.md) |

These are small paired experiments, not promises of universal improvement.
Read the [method and captured results](benchmarks/measured/2026-09-07/README.md)
before interpreting a number. Structural validation, fixture checks, rollout
observations, and held-out validation are [different evidence tiers](docs/catalog-eval-tiers.md).

## Catalog

Browse the searchable catalog at [lab.abvx.xyz/tools/abvx-agent-skills/](https://lab.abvx.xyz/tools/abvx-agent-skills/). The page is powered by the generated catalog data in [docs/catalog.json](docs/catalog.json), so the repository remains the source of truth while the published catalog lives on ABVX Lab.

If you want a scan-friendly text catalog for browsing or indexing, use [CATALOG.md](CATALOG.md).

## External companion for modern web work

[GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance)
is the recommended source for current browser APIs, compatibility-aware fallbacks,
accessibility, CSS, forms, and web performance patterns. Use it only for browser-facing
HTML, CSS, and client-side JavaScript work. It complements `frontend-product-builder`,
`web-quality-audit`, and `browser-verification`; it is not bundled here and its results
do not replace ABVX validation or browser evidence.

For Codex:

```bash
codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome
```

The external tool collects guide IDs and agent-generated search queries by default.
Set `DISABLE_TELEMETRY=1` in the shell environment to opt out. Review its
[telemetry notes](https://github.com/GoogleChrome/modern-web-guidance#telemetry--privacy)
and preview-release status before team-wide adoption.

## Companion contracts

Some useful repo surfaces are companion contracts rather than installable skill entries.

- [docs/ship-router-contract.md](docs/ship-router-contract.md) — choose `direct`, `review_first`, `bounded_loop`, `human_gate`, or `blocked` before execution widens or a ship claim is made.
- [docs/quality-eval-and-catalog-hygiene-contract.md](docs/quality-eval-and-catalog-hygiene-contract.md) — keep the public pack, generated catalog, and skill truth aligned.
- [docs/catalog-drift-and-distribution.md](docs/catalog-drift-and-distribution.md) — define what belongs in GitHub, Lab, and generated distribution surfaces.
- [docs/superpowers-skill-discipline-note.md](docs/superpowers-skill-discipline-note.md) — adapt Superpowers-style trigger, verification, and skill-behavior discipline without importing the full workflow.
- [docs/generated-skill-review-gate.md](docs/generated-skill-review-gate.md) — treat generated skills as proposal drafts until source, eval, catalog, and maintainer review pass.
- Security-review repo selection belongs in `SET`: [docs/codex-security-repo-selection-matrix.md](https://github.com/markoblogo/SET/blob/main/docs/codex-security-repo-selection-matrix.md).
- Search-discoverable code guidance lives in [docs/search-discoverable-code-note.md](docs/search-discoverable-code-note.md) here and the broader contract belongs in `SET`: [docs/search-discoverable-code-contract.md](https://github.com/markoblogo/SET/blob/main/docs/search-discoverable-code-contract.md).

## Start With One Job

| Job | Install | Use when |
|---|---|---|
| Write smaller patches | `minimal-diff-builder` | The agent keeps refactoring too much, widening blast radius, or adding abstractions you did not ask for. |
| Debug from evidence | `diagnose` | The agent keeps guessing fixes without reproducing the failure and verifying the result. |
| Prove a regression fix | `bug-evidence-protocol` | A diagnosed bug needs captured same-command red/green evidence, broader checks, Git identity, and an honest fix status. |
| Harden repeated runtime sprints | `loop-hardening-contract` | Cardputer, browser, CI, or production work needs measured harness stripping, immutable runtime-path predicates, and broken-window revalidation without automatic revert. |
| Review plans before work | `assumption-excavation`, `pipeline-readiness-gate` | A plan, SET bundle, or spec sounds plausible but may hide assumptions or missing gates. |
| Coordinate reviewed multi-agent work | `bounded-orchestration-contract` | A non-trivial task benefits from Planner/Reviewer approval, stable findings, disjoint executor ownership, explicit route evidence, and root verification. |
| Preserve typed project truth | `git-native-context-contract` | Decisions, rules, specs, plans, bounded research, or recurring incident lessons need a minimal Git-reviewed lifecycle and relation contract. |
| Run reversible agent work | `reversible-agent-task` | A task should produce retained output first, then move through inspect -> select/apply/discard before touching the target workspace. |
| Continue a Codex task from Android | `happy-handoff` | The user says `ухожу` or explicitly asks to resume the same active Codex Desktop task through Happy. |
| Check ship confidence | `confidence-fragility-review`, `delivery-baseline-audit` | A release, README, generated plan, or PR sounds done but evidence may be thin. |
| Choose the right delivery lane before shipping | `docs/ship-router-contract.md` | Work may need `direct`, `review_first`, `bounded_loop`, or `human_gate` routing before implementation widens or a ship claim is made. |
| Save tokens in shell-heavy work | `rtk-assisted-shell`, `shell-output-compaction`, `token-efficient-execution` | Logs, diffs, tests, and command output are burning context and hiding the real signal. |
| Verify frontend work | `browser-verification`, `design-critique-polish`, `motion-review-gate`, `fluid-interaction-review` for drag/swipe physics | The agent says "done" without checking real browser behavior, layout, states, motion, gesture continuity, or console errors. |
| Govern named agents, long operations, and durable decisions | `agent-operations-contract`, `agent-tool-contract-review`, `loop-readiness-review` | Agent configuration, schedules, memory, providers, operation status, or decision records are mistaken for authority or verified outcomes. |

## LoopOps

LoopOps is the framework layer in this repo: it decides when a repeated prompt should remain a prompt and when it should become a checklist, skill, script, or bounded loop.

See:

- [docs/loopops-guide.md](docs/loopops-guide.md)
- `loopops-protocol`
- `dynamic-workflow-packets`
- `skillopt-evolve-skills`

The next LoopOps layer is bounded skill evolution: see [docs/skill-evolution-roadmap.md](docs/skill-evolution-roadmap.md) and the manual-pilot manifest in [benchmarks/skill-evolution/manifest.json](benchmarks/skill-evolution/manifest.json). Start with one or two repeated skills, treat the skill as a versioned artifact, capture rollout evidence, keep edits bounded, validate against held-out or independent cases, retain rejected proposals as negative feedback, and export `best_skill.md` only after maintainer acceptance.

For the public pack and searchable catalog, also keep catalog text source-linked, concise, and drift-checked against real skill files. See [docs/quality-eval-and-catalog-hygiene-contract.md](docs/quality-eval-and-catalog-hygiene-contract.md).
Use [docs/catalog-schema-hardening.md](docs/catalog-schema-hardening.md), [docs/catalog-eval-tiers.md](docs/catalog-eval-tiers.md), and [docs/catalog-drift-and-distribution.md](docs/catalog-drift-and-distribution.md) for the follow-up rules.
For delivery-lane choice before a ship claim, use [docs/ship-router-contract.md](docs/ship-router-contract.md).

<p>
  <img src="assets/loopops-landscape.png" alt="LoopOps promotion ladder from prompt to checklist, skill, script, or bounded loop" width="1280">
</p>

## Choose A Workflow

Start with one skill. Use the [selection guide](docs/skill-selection-guide.md) when your task needs a broader workflow.

## Skills

These skills are grouped by the job they do. The token-economy layer is intentionally visible first: for many teams, the easiest win is not “a smarter prompt”, but less wasted context.

### Token Economy & Context Control

| Skill | What It Does |
|---|---|
| `rtk-assisted-shell` | Routes noisy shell workflows through RTK-style filtering. Measure command-output reduction on your own tasks; it is not a claim about total session cost. |
| `shell-output-compaction` | Shrinks logs, diffs, and repo search output into counts, slices, and error-first excerpts. Usually the fastest way to turn multi-screen stdout into a small, usable artifact. |
| `graph-guided-code-reading` | Replaces broad repo reading with entrypoints, symbols, dependencies, and blast radius. On large codebases this can turn “read everything” into a much smaller focus set. |
| `context-degradation-review` | Reviews context poisoning, lost-in-the-middle failures, distraction, context clash, and stale carryover before they degrade agent behavior. |
| `token-efficient-execution` | Cuts waste from repeated reads, broad rewrites, and low-value narration. Best for long coding sessions where the loop, not the final answer, is burning the budget. |
| `token-frugal-mode` | Compresses final answers without dropping the decisive technical signal. Useful when the session is tight and you want shorter replies without caveman-style degradation. |
| `lean-context-layout` | Shrinks always-loaded agent docs into a compact startup core and pushes the rest on demand. Best for bloated `AGENTS.md`, `CLAUDE.md`, and repo runbooks. |
| `compaction-survival` | Preserves the high-value working state before long sessions collapse into compaction. Saves the turns you would otherwise spend reconstructing “what were we doing?”. |
| `token-usage-audit` | Diagnoses where the budget is really going: startup bloat, shell noise, repeated reads, oversized summaries, or compaction loss. Use this before over-optimizing the wrong layer. |

### Coding, Debugging & Architecture

| Skill | What It Does |
|---|---|
| `diagnose` | Runs a disciplined debugging loop around one reproducible signal, ranked hypotheses, and narrow verification. |
| `bug-evidence-protocol` | Captures same-command red/green evidence, broader checks, Git/environment identity, route state, and an honest fix classification after diagnosis. |
| `agent-tool-contract-review` | Reviews MCP tools, CLI commands, SET inputs, AGENTS.md generator outputs, and external-skill adaptation deltas as agent-facing contracts with explicit authority and output boundaries. |
| `repo-debugging-ledger` | Keeps a checked-location ledger so debugging does not keep reopening the same code and repeating the same dead ends. |
| `complexity-optimizer` | Finds safe complexity and performance simplifications without turning the codebase into a refactor festival. |
| `minimal-diff-builder` | Builds the smallest correct implementation path using a YAGNI, stdlib-first, native-first, minimal-diff ladder with explicit safety exceptions. |
| `overengineering-review` | Reviews code specifically for needless abstractions, replaceable dependencies, dead flexibility, and wrappers over stdlib or platform behavior. |
| `architecture-deepening-review` | Reviews deeper module seams, coupling, change surfaces, and testability, not just top-level architecture slogans. Pair with `html-diagram-artifact` or `html-brief-artifact` when the output should be a browser-readable architecture report. |
| `test-driven-execution` | Builds features and fixes through one-behavior-at-a-time red-green-refactor loops instead of broad speculative implementation. |
| `system-zoom-out` | Pulls a local code area back into its wider system map so you can reason about callers, modules, boundaries, and blast radius. |
| `local-inference-tuning` | Selects and tunes local LLM engines around hardware, model fit, cache policy, KV cache, batching, and OpenAI-compatible endpoints. |
| `agents-best-practices` | Hardens agent harnesses around permissions, context shape, safety, and evaluation discipline. |
| `skillopt-evolve-skills` | Improves agent instructions and skills from real task evidence rather than from theory alone. |

### Frontend, UX & Product Surfaces

| Skill | What It Does |
|---|---|
| `design-register-bootstrap` | Establishes compact design context before implementation: `brand` vs `product` register, audience, creator intent, preserve-theirs constraints, anti-references, color strategy, and PRODUCT.md / DESIGN.md direction. |
| `frontend-taste-layer` | Sets and reviews marketing/editorial visual direction through a design read, creator-intent check, relative composition/motion/density, preservation-first redesign, layout rhythm, and browser evidence; product UI routes to Lazyweb and UX review. |
| `fluid-interaction-review` | Reviews direct-manipulation physics: 1:1 tracking and grab offset, pointer capture, current-value interruption, velocity handoff, momentum projection, hysteresis, soft boundaries, spatial continuity, and independent motion/transparency/contrast fallbacks. |
| `anti-slop-review` | Reviews implemented UI and public prose for hard defects, incoherence, template risk, and AI-writing tells with stable evidence-backed findings instead of blanket aesthetic or voice bans. |
| `design-critique-polish` | Runs a focused critique-and-polish pass to rank frontend issues, identify ship blockers, and tighten hierarchy, typography, color, and states. |
| `frontend-product-builder` | Builds usable frontends, landing pages, pitch pages, dashboards, and prototypes with a product-first interaction model. |
| `lottie-motion-builder` | Builds small production-ready Lottie assets from SVGs, logos, loaders, and UI states with a local preview harness and output verification. |
| `motion-review-gate` | Reviews frontend motion before shipping: purpose, frequency, easing, duration, origin, interruptibility, GPU-safe properties, and reduced-motion support. |
| `designmd-brand-kit` | Turns a website or brand surface into an agent-usable design system: structure, identity, and reusable UI cues. |
| `browser-verification` | Verifies real browser rendering, responsive layout, and interaction behavior instead of trusting static code inspection. |
| `web-quality-audit` | Audits accessibility, performance, UX, privacy, and browser security as one practical web quality pass. |
| `prototype-lab` | Rapid throwaway builds for testing interaction, logic, and product direction before committing to heavier implementation. |

### HTML Artifacts & Visual Deliverables

| Skill | What It Does |
|---|---|
| `html-diagram-artifact` | Creates standalone HTML/SVG diagrams for architecture, request paths, component relationships, and system explainers with minimal prose and browser-verifiable dark mode. |
| `html-brief-artifact` | Creates standalone HTML briefs for plans, status updates, PR summaries, incident notes, and research explainers without drifting into a full frontend build. |

### Project Context & Onboarding

For design-heavy repos, pair this section with `design-register-bootstrap` from the frontend section.

| Skill | What It Does |
|---|---|
| `project-context-bootstrap` | Detects the stack, asks the right project questions, and turns a weakly documented repo into a compact, agent-usable context surface. |
| `filesystem-context-discipline` | Uses typed files for scratchpads, plans, evidence, retained outputs, and handoffs without polluting always-loaded prompt context. |
| `rabbithole-doc-exploration` | Opens AGENTS.md, skill docs, SET plans, repomaps, or seed docs in an optional local Rabbithole canvas for human-selected branch questions. |
| `durable-context-maintenance` | Keeps repo-local context current after architecture, workflow, and test-flow changes so agents stop rediscovering the same facts. |
| `personal-workspace-router` | Creates a local root router with isolated domain folders, user-triggered memory, decision logs, and routing corrections for multi-project operator work. |

### Discovery, Planning & Delivery

| Skill | What It Does |
|---|---|
| `rapid-grilling` | Quickly sharpens vague ideas through one-question-at-a-time alignment before heavier planning starts. |
| `doc-grounded-grilling` | Stress-tests a plan against repo docs, ADRs, design assets, and domain language so discovery stays grounded in reality. |
| `assumption-excavation` | Surfaces hidden environment, dependency, behavioral, temporal, and success assumptions in plans, docs, skills, and SET bundles. |
| `spec-to-prd` | Turns clarified context into a durable PRD for product, client, and internal roadmap work. |
| `plan-to-issues` | Breaks PRDs and plans into thin end-to-end slices that agents or humans can actually pick up. |
| `repo-issue-triage` | Moves bugs and enhancements through a compact state machine so backlog items become actionable instead of vague. |

### Research, Knowledge & Reusable Methods

| Skill | What It Does |
|---|---|
| `bounded-evaluation` | Designs small eval gates with fixtures, rubrics, pairwise checks, position-bias mitigation, and explicit accept/reject/revise decisions. |
| `evidence-ledger-research` | Keeps claims, sources, calculations, and open questions in a disciplined evidence ledger. |
| `hypothesis-diversification` | Generates diverse hypotheses, explanations, or bounded proposals before evidence review and adversarial validation. |
| `social-publishing-gate` | Gates social posts, replies, scheduling, and monitoring through draft, audit, approval, publish, and monitor steps. |
| `loopops-protocol` | Chooses when repeated agent work should stay a prompt or be promoted into a skill, checklist, script, workflow, or cost-bounded loop. |
| `agent-learning-layer-triage` | Routes agent lessons into the right auditable layer: prompt, memory, durable docs, checklist, skill, script, eval, or rejected buffer. |
| `book-to-skill` | Converts books, papers, and long documents into reusable, progressive-disclosure agent skills. |
| `doc-to-lora-evaluator` | Evaluates whether document-to-adapter memory is worth a proof-of-concept before building a Doc-to-LoRA plugin or pipeline. |
| `goal-loop-designer` | Compiles raw agent goals into bounded loop harnesses with stop rules, rubric, judge prompt, budgets, and portable artifacts. |
| `role-skill-pack-design` | Designs compact role/workflow skill packs with base layers, difference layers, boundaries, and rollout order. |
| `workflow-policy-layering` | Separates workflow from authority, escalation, forbidden actions, and validation so assistant specs stop contradicting themselves. |
| `brief-first-execution` | Starts non-trivial work with one live brief for scope, non-goals, risks, verification, and done criteria. |
| `private-vs-publishable-skill-audit` | Audits private skill packs before publication and extracts only the reusable layer. |
| `agent-friction-ledger` | Captures repeated agent blockers, doc gaps, tool incompatibilities, and workarounds as local, privacy-safe reports that can feed docs, skills, scripts, or evals. |
| `knowledge-base-enrichment` | Enriches Markdown notes and wikis with provenance while preserving raw sources and review boundaries. |
| `git-native-context-contract` | Keeps typed project truth, decisions, and incident lessons reviewable through a human-gated Git lifecycle. |
| `skill-health-audit` | Audits trigger fit, evidence depth, drift, overhead, safety, and evaluation readiness without editing the audited skill. |

### Product Context & Responsible Growth

| Skill | What It Does |
|---|---|
| `product-context` | Builds a compact, evidence-backed product context with audience, conversion, proof, language, and claim boundaries before go-to-market work. |
| `bounded-growth-loop` | Designs recurring content, SEO, analytics, or product-review loops with durable state, verification, stop rules, and approval-gated outputs. |

### Workflow, Handoffs & Multi-Track Work

| Skill | What It Does |
|---|---|
| `dynamic-workflow-packets` | Orchestrates large coding, research, audit, harness, or client-search tracks without losing verification, budgets, integration, and risk gates. |
| `loop-readiness-review` | Checks whether a recurring agent loop has cadence, state, isolation, verifier, budget, run log, rollback, and human gate before it runs. |
| `loop-hardening-contract` | Adds measured harness stripping, immutable runtime-path sprint packets, and broken-window revalidation without automatic revert. |
| `pipeline-readiness-gate` | Selects a compact pre-implementation, post-implementation, or ship gate without adopting a heavy multi-agent pipeline runtime. |
| `reversible-agent-task` | Runs risky or multi-file agent work as retained output, then requires inspect -> select/apply/discard before target workspace mutation. |
| `handoff` | Produces compact continuation briefs for long-running work, agent resumes, and human handoffs. |
| `happy-handoff` | Schedules the exact active Codex Desktop task to resume in Happy on Android while preserving its workspace and approval boundaries. See the [local pilot](docs/demos/happy-handoff.md). |
| `agent-operations-contract` | Governs named agents, operation receipts, decisions, memory, provider evidence, and approval boundaries. |
| `bounded-orchestration-contract` | Coordinates reviewed Planner/Reviewer/Executor work with stable findings, disjoint ownership, and root verification. |

### Long-Run Delivery Control

| Skill | What It Does |
|---|---|
| `idea-to-ship-gates` | Routes ideas through intent, spec, slices, architecture, proof, convergence, and release gates. |
| `delivery-preflight-gate` | Runs the minimum useful baseline checks before a long implementation loop or PR publication, so pre-existing breakage and noisy branches do not poison later verification. |
| `phase-spec-execution` | Breaks larger delivery into explicit phases with acceptance criteria, verification commands, and lightweight state updates. |
| `recovery-loop-3strike` | Bounds execution failure handling to one evidence-bearing retry, one focused fix-spec, and then an honest blocker handoff. |
| `confidence-fragility-review` | Checks whether confident claims in plans, docs, releases, or workflow contracts are backed by evidence. |
| `delivery-baseline-audit` | Re-checks declared deliverables and final verification against the starting baseline and full working tree before calling the task complete. |
| `public-release-verification` | Proves release status across package, deploy, HTTP, browser, locale, visual, and human approval gates. |

### Security & Defensive Review

| Skill | What It Does |
|---|---|
| `authorized-security-router` | Routes authorized defensive security and reverse-analysis tasks by scope, target type, intent, toolchain, and blocked-action gates. |

### Structured Data & Spreadsheet Work

| Skill | What It Does |
|---|---|
| `spreadsheet-workbook-forensics` | Repairs and edits spreadsheets where workbook structure, formulas, and cell-level verification matter. |

## Install

Install the three-skill starter set:

```bash
pip install abvx-agent-skills
abvx-skills install minimal-diff-builder diagnose token-efficient-execution
```

If PyPI is temporarily unavailable, use GitVerse's PyPI mirror for that install command only:

```bash
python -m pip install abvx-agent-skills --index-url https://pypi-mirror.gitverse.ru/simple/
```

Install with GitHub CLI agent-skills support:

```bash
gh skill install markoblogo/abvx-agent-skills minimal-diff-builder
```

Target a specific host or scope when needed:

```bash
gh skill install markoblogo/abvx-agent-skills minimal-diff-builder --agent codex --scope user
gh skill install markoblogo/abvx-agent-skills diagnose --agent cursor --scope project
```

`gh skill` is currently a GitHub CLI preview feature. Use GitHub CLI `v2.90.0+`. The command set and flags are documented in the official [`gh skill`](https://cli.github.com/manual/gh_skill) manual and the GitHub changelog announcement for [GitHub CLI agent skills](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/).

Published package pages:

- PyPI: <https://pypi.org/project/abvx-agent-skills/>
- TestPyPI: <https://test.pypi.org/project/abvx-agent-skills/>

Current distribution channels:

- PyPI: published
- TestPyPI: published
- conda-forge: staged-recipes submission currently open at <https://github.com/conda-forge/staged-recipes/pull/33719>

Distribution boundaries for repo, Lab, and package surfaces are summarized in [docs/catalog-drift-and-distribution.md](docs/catalog-drift-and-distribution.md).

Install the packaged CLI from PyPI:

```bash
uv tool install abvx-agent-skills
```

Install one skill into Codex:

```bash
git clone https://github.com/markoblogo/abvx-agent-skills
cp -R abvx-agent-skills/skills/dynamic-workflow-packets ~/.codex/skills/
```

Install all skills:

```bash
git clone https://github.com/markoblogo/abvx-agent-skills
cp -R abvx-agent-skills/skills/* ~/.codex/skills/
```

Start a new agent session after installation so the skill descriptions are discovered.

Install one packaged skill into Codex:

```bash
abvx-skills install dynamic-workflow-packets
```

Install to a custom destination:

```bash
abvx-skills install --destination ./tmp-skills
```

Smoke-test the published package from PyPI:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install abvx-agent-skills
abvx-skills list
abvx-skills validate
```

## Safety And Auditability

Before installing a skill, inspect it:

```bash
gh skill preview markoblogo/abvx-agent-skills minimal-diff-builder
```

Validate local or packaged skills:

```bash
abvx-skills validate
gh skill publish --dry-run
```

Run the static security audit:

```bash
abvx-skills audit-security ./skills --no-llm
```

This repository is intentionally optimized for inspection before trust: compact skill files, reviewable metadata, structural validation, and a publish dry-run that catches naming and metadata drift before release.

## Onboarding Paths

- **Solo dev in Codex / Cursor / Claude Code / Gemini CLI:** use [docs/solo-dev-quickstart.md](docs/solo-dev-quickstart.md) for a short install path plus a recommended starter stack.
- **Team lead standardizing repo work:** use [docs/team-rollout-playbook.md](docs/team-rollout-playbook.md) for the minimum shared-skill rollout and repo hygiene path.

## Demos

- [docs/demos/minimal-diff-builder.md](docs/demos/minimal-diff-builder.md)
- [docs/demos/diagnose.md](docs/demos/diagnose.md)
- [docs/demos/token-economy.md](docs/demos/token-economy.md)

## Distribution

If you are listing the repo in curated skill directories, agent catalogs, or install surfaces, use [docs/outreach/submission-kit.md](docs/outreach/submission-kit.md) for positioning and [docs/outreach/targets.md](docs/outreach/targets.md) for target tracking.

Catalog and publish discipline for the pack itself lives in [docs/quality-eval-and-catalog-hygiene-contract.md](docs/quality-eval-and-catalog-hygiene-contract.md).
Schema expectations, eval tiers, and drift/distribution rules live in [docs/catalog-schema-hardening.md](docs/catalog-schema-hardening.md), [docs/catalog-eval-tiers.md](docs/catalog-eval-tiers.md), and [docs/catalog-drift-and-distribution.md](docs/catalog-drift-and-distribution.md).

For the current first-wave outreach set, use [docs/outreach/first-wave-submissions.md](docs/outreach/first-wave-submissions.md).

## Repository Profile

Each public skill includes:

- `SKILL.md` - executable agent instructions
- `SKILL_CARD.md` - intended use, attribution, risks, evaluation, and version
- `agents/openai.yaml` - Codex UI metadata

The project follows the open Agent Skills shape: `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. For Codex compatibility, top-level frontmatter is kept conservative: `name`, `description`, `license`, `metadata`, and supported fields only.

The HTML artifact skills intentionally keep their deliverables single-file and dependency-light. Use them for explainers and briefs, not as substitutes for production frontend implementation.

## Contribute

### How To Contribute Your Own Skills

Use this repo when a workflow has repeated often enough that it deserves a sharper portable behavior layer, not when you just have a long prompt.

Contribution path:

- **Submit your own skill:** draft it against [docs/abvx-skillpack-profile.md](docs/abvx-skillpack-profile.md), mirror the shape of an existing skill, and open a PR with the smallest useful slice.
- **Request a missing skill:** open a [Skill Request](https://github.com/markoblogo/abvx-agent-skills/issues/new?template=skill-request.yml) when the repeated workflow is real but the right skill does not exist yet.
- **Autopsy a broken skill:** open a [Skill Autopsy](https://github.com/markoblogo/abvx-agent-skills/issues/new?template=skill-autopsy.yml) when an internal or external skill added noise, abstractions, or fake process and should be reduced into something stronger.

Good submissions usually have:

- a narrow trigger, not a vague domain
- one clear behavior change
- explicit anti-patterns or stop conditions
- honest verification instead of broad motivational prose

Use [docs/solo-dev-quickstart.md](docs/solo-dev-quickstart.md) and [docs/team-rollout-playbook.md](docs/team-rollout-playbook.md) as examples of opinionated packaging aimed at real adoption paths rather than generic documentation.

## Validate

```bash
python scripts/validate.py
```

Or validate the packaged skills through the CLI:

```bash
abvx-skills validate
```

Run a static security audit with SkillSpector:

```bash
pip install git+https://github.com/NVIDIA/SkillSpector.git
abvx-skills audit-security ./skills --no-llm
```

Evaluate reports against the repo policy and baseline:

```bash
python scripts/evaluate_skillspector.py \
  --reports-dir artifacts/skillspector \
  --policy .abvx/skillspector-policy.yaml \
  --baseline .abvx/skillspector-baseline.json
```

Validate a local skills directory:

```bash
abvx-skills validate ~/.codex/skills
```

Structural validation and security audit are separate gates. The validator checks required files, frontmatter, directory/name alignment, TODO placeholders, cards, UI metadata, and basic secret patterns.

## Benchmarks

The [measured demos](benchmarks/measured/2026-09-07/README.md) retain paired runs, fixtures, raw traces, and deterministic checks for three skills. They are small single-model pilots; broader effectiveness and held-out validation remain unproven.

## Release

Build and check the package locally:

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

Publish flow:

- Run the `publish` GitHub Actions workflow with `repository=testpypi` for a dry run against TestPyPI.
- Create a GitHub release, or run the same workflow with `repository=pypi`, to publish to PyPI.
- Configure trusted publishing for both `pypi` and `testpypi` environments in the package index before the first release.
- Keep the released version aligned with `pyproject.toml` and the skill inventory documented above.

## Philosophy

- Keep always-loaded context small.
- Prefer procedural rules over vague advice.
- Make skills easy to audit in diffs.
- Attribute upstream inspiration.
- Pair useful automation with risk gates and verification.

See [docs/abvx-skillpack-profile.md](docs/abvx-skillpack-profile.md) for the repository standard.

## Attribution

Several skills are inspired by public work from the broader agent tooling ecosystem. See [ATTRIBUTION.md](ATTRIBUTION.md).

## License

MIT. See [LICENSE](LICENSE).
