operational-value-designer

Designs and verifies deterministic operational-value graders for GitHub Agentic Workflows.

5.1k|530|Updated Aug 12, 2025
One-click install
npx skills add https://github.com/github/gh-aw --skill operational-value-designer
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: operational-value-designer
Source: https://github.com/github/gh-aw/tree/main/.github/skills/operational-value-designer
Command: npx skills add https://github.com/github/gh-aw --skill operational-value-designer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, gh, and includes scripts (resource) components.

What problem does it solve?

Measuring whether an agentic workflow actually achieves its intended repository outcome is hard: raw activity counts and agent self-assessments do not prove attainment. This Skill designs a deterministic operational-value grader that scores each workflow run against frozen, evidence-based criteria.

Core Features & Use Cases

  • Grader Generation: Creates one executable Bash evaluator at .github/graders/WORKFLOW-NAME-operational-value.sh implementing the schema-version 4 definition contract with --definition, --metric, and --grade-run interfaces.
  • Evidence & Baseline Freezing: Recovers adoption-time intent from the workflow's first commit, freezes accepted evidence, maturation rules, and an optional pre-adoption baseline for delta computation.
  • Verification & Reporting: Validates evaluators with the bundled verification script, supports regrading historical runs, and builds JSON/SVG/Markdown reports across all completed runs.
  • Use Case: After deploying an issue-triage agentic workflow, use this Skill to build a grader that scores each run by whether the assigned issue actually received the intended repository outcome, then track weekly attainment trends against a frozen baseline.

Quick Start

Ask the agent to design an operational-value grader for your repository and workflow by running /operational-value-designer with your OWNER/REPO and workflow name.

Frequently Asked Questions about operational-value-designer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an operational-value grader for a GitHub Agentic Workflow?

Invoke the skill with /operational-value-designer OWNER/REPO WORKFLOW-NAME. It generates an executable evaluator at .github/graders/WORKFLOW-NAME-operational-value.sh and configures the workflow's graders section to run it.

How do I verify an operational-value evaluator script?

Run the bundled verify-operational-value-evaluator.sh script with the evaluator path. It checks the definition contract against schema version 4, validates metric outputs on the four validation examples, and tests a synthetic --grade-run request.

What is the difference between value and deltaFromBaseline in operational-value grading?

The value field is absolute attainment in [0,1] for the run's assigned opportunity. deltaFromBaseline is derived by gh-aw as the difference from a frozen pre-adoption baseline and must never be defined as the primary value.

Can I regrade a historical workflow run with a specific evidence time?

Yes, use gh aw graders operational-value RUN-ID with --evidence-at to recompute an observation. The command reuses the archived evaluator after verifying its digest against the recorded commit and never modifies the original artifact.

What permissions does the operational-value evaluator need?

The evaluator receives GH_TOKEN with the agent job's declared permissions, so the workflow must declare only the permission scopes required to collect its accepted evidence. gh-aw does not add evidence permissions automatically.