feat(skills): introduce cluster toolkit agent skills, evals and gke-kueue debugging skill

[shubpal07]

Overview

This PR introduces the Agent Skills Framework to Cluster Toolkit along with the gke-kueue-debugging reference skill and offline evaluation infrastructure.

The framework is aligned with the open agentskills.io specification, enabling AI coding agents (such as Gemini Code Assist, Antigravity, Claude Code, Cursor, Windsurf, GitHub Copilot, etc) to provide domain-specific diagnostic and operational assistance for Google Cloud HPC and AI/ML infrastructure without requiring external API keys, runtime tokens, or cloud permissions during presubmit.

---

Key Deliverables

1. Specification & Authoring Guide (skills/)

• skills/README.md: Complete contributor specification covering the 3-tier progressive disclosure model (Metadata -> Stepwise Instructions -> On-demand References), frontmatter schema rules, safety protocols (read-only command isolation, confirmation gating), and evaluation authoring guide.
• skills/gke-kueue-debugging/: Reference skill providing structured, non-destructive diagnostic workflows for GKE Kueue batch admission, cohort borrowing, ResourceFlavor taints/labels, Head-of-Line (HOL) blocking, and GKE DWS Flex-start integration.
• skills/gke-kueue-debugging/references/: Tier 3 progressive disclosure technical documentation detailing official Kueue APIs (kueue-docs.md) and GKE Cohort quota architectures (gke-kueue-docs.md).

2. Evaluation & Linting Engine (tools/run_eval.py)

• Tier 1 Static Frontmatter Linter: Validates YAML frontmatter formatting, field naming parity with parent directories, description character budgets, and experimental warning callout enforcement.
• Tier 2 Deterministic Evaluation Runner: Executes mock offline evaluations verifying assertion satisfiability (expect_keywords_all, expect_keywords_any, expect_blocked_action) and regex-bounded safety constraints (forbidden_commands).
• Safety Protocol Enforcement: Verifies that any mutating command (e.g. kubectl delete, helm uninstall, terraform destroy) is blocked unless explicitly gated inside a [PROPOSED REMEDIATION PLAN] requiring human operator confirmation.

3. Comprehensive Unit Test Suite (tools/tests/test_run_eval.py)

• 49 Passing Unit Tests: Covers YAML frontmatter parsing, whitespace/CRLF safety, normalization, boundary-safe CLI command tokenization, schema verification, and exit code contracts (runs in ~0.06s).

4. CI/CD Automation & Developer Ergonomics

• GitHub Actions (.github/workflows/skills-lint.yml): Automated presubmit CI workflow running static linting, offline mock evals, and unit tests on PRs modifying skills or evaluation tools.
• Pre-commit Integration (.pre-commit-config.yaml): Added local skills-lint pre-commit hook and excluded frontmatter markdown from PyMarkdown MD041.
• Makefile Targets (Makefile): Added make lint-skills and make test-skills shortcuts matching repository developer conventions.

---

Verification & Test Results

• Local Test Suite:

  $ make lint-skills && make test-skills
  [PASS] gke-kueue-debugging (Lint): Valid frontmatter and EVAL.yaml schema
  Ran 49 tests in 0.061s (OK)
  [PASS] gke-kueue-debugging (Eval): All 7 cases passed
  Result: ALL CHECKS PASSED
  
  
  
  

Submission Checklist

NOTE: Community submissions can take up to 2 weeks to be reviewed.

Please take the following actions before submitting this pull request.

• Fork your PR branch from the Toolkit "develop" branch (not main)
• Test all changes with pre-commit in a local branch #
• Confirm that "make tests" passes all tests
• Add or modify unit tests to cover code changes
• Ensure that unit test coverage remains above 80%
• Update all applicable documentation
• Follow Cluster Toolkit Contribution guidelines #

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes a robust framework for integrating AI-driven diagnostic and operational skills into the Cluster Toolkit. By providing a standardized specification for skill authoring, a deterministic evaluation engine, and automated CI/CD pipelines, it enables developers to create safe, domain-specific diagnostic workflows for complex HPC and AI/ML infrastructure, starting with a comprehensive reference implementation for GKE Kueue debugging.

Highlights

• Agent Skills Framework: Introduced a standardized framework for authoring and managing AI agent skills, aligned with the agentskills.io specification.
• GKE Kueue Debugging Skill: Added a reference skill providing structured, non-destructive diagnostic workflows for GKE Kueue batch admission and infrastructure troubleshooting.
• Evaluation & Linting Engine: Implemented tools/run_eval.py to perform static frontmatter linting and deterministic offline evaluation of skill assertions.
• CI/CD & Developer Ergonomics: Integrated automated linting and testing via GitHub Actions, pre-commit hooks, and new Makefile targets to ensure skill quality.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/skills-lint.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new agent skills framework for the Cluster Toolkit, including a comprehensive GKE Kueue debugging playbook, reference documentation, and an offline evaluation runner (tools/run_eval.py) with associated unit tests. The review feedback highlights critical improvements: addressing a potential safety bypass in the evaluation runner's response scanning logic, correcting an unsupported field selector on Kueue Workload CRDs, and fixing a logical AND label selector bug that would prevent GKE accelerator nodes from being listed correctly.

[gokamesh]

nit: to avoid same skill name from other sources, consider prefixing the skills with ct or gct.