How to use the AegisOps-AI Governance Guardrails agent skill

What the aegisops-ai skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells the agent when a task fits and how to approach it. Once this skill is loaded, the agent knows the AegisOps-AI workflow and can guide you through it when your request matches one of its three modules.

The skill itself is only a guide. The actual scripts, patch_analyzer.py, cost_auditor.py and k8s_policy_generator.py, live in a separate upstream repository and are not bundled with the skill. The skill tells you to verify that upstream repository, a fixed revision, its licence and its dependencies before you use it.

• Kernel Patch Reviewer (patch_analyzer.py): proposes findings on raw Git diffs, such as logic-based issues like use-after-free and stale state. Key output: analysis_results.json
• FinOps and Cloud Auditor (cost_auditor.py): analyses terraform plan output for cost anomalies, such as an accidental upgrade from t3.micro to a GPU instance. Key output: infrastructure_audit_report.json
• K8s Policy Hardener (k8s_policy_generator.py): turns plain-language security requirements into candidate YAML manifests, for example read-only root filesystem or non-root enforcement. Key output: hardened_deployment.yaml

Install the skill from the ZIP or the Claude apps

Download the skill ZIP from the page where you found this guide. Then choose one of two routes depending on how you use Claude.

For Claude Code, unzip the download into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project. The skill folder should contain SKILL.md.

In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills instead of unzipping it by hand.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Apps install: Settings, then Capabilities, then Skills

Prepare the upstream tool and its requirements

Running the actual analysers requires the upstream AegisOps-AI repository, cloned separately. The skill's own setup notes show the clone, a Python virtual environment and the two Python packages the upstream tool uses. Check the upstream repository, a fixed revision and its licence before you run anything from it.

You also need a GEMINI_API_KEY from a Google GenAI account with paid model access. Use your host's existing private credential mechanism for the key. In production, the skill recommends CI/CD secrets.

• Python 3 with a virtual environment
• google-genai and python-dotenv Python packages
• A GEMINI_API_KEY from a Google GenAI account with paid model access
• The upstream AegisOps-AI repository cloned at a verified revision

Trigger the skill with natural requests

You do not need special syntax. Describe the task in plain language and name the artefact you have, such as a Git diff, a terraform plan output or a deployment that needs hardening. The skill is also listed under the command name /aegisops-ai in its own heading.

Give the agent enough context to work with. The skill recommends at least 5 lines of context around Git diffs for more accurate reasoning, and it expects you to state the security intent you want for Kubernetes, such as non-root only.

• Review this kernel patch diff for memory-safety problems. Here are 5 lines of context around each change.
• Check this terraform plan output for cost increases before I apply it.
• Harden this deployment so it runs as non-root and uses a read-only root filesystem.
• Explain which findings I need to verify by hand before merging.

Work through the three checks

Each module has a different input and a different kind of output. Treat every output as a candidate finding. The kernel reviewer gives findings to verify through code review and appropriate tests, with no detection guarantee. The cost auditor flags anomalies that someone should confirm against the real plan. The Kubernetes hardener produces candidate YAML that still needs schema, policy and application validation.

The skill's main Kubernetes pattern is an over-privileged container. Look for allowPrivilegeEscalation set to true or root user execution, then pass the security intent to the hardener.

• Kernel patches: paste the raw C diff with context and ask for memory-safety findings.
• Terraform: paste the plan output and ask which resources would become much more expensive.
• Kubernetes: describe the required security settings and ask for a hardened securityContext.

Safety, data and cost notes

The analysers send your input to a paid third-party model API. Only proceed if you are authorised to send private patches, cluster configurations or cloud plans to that service. Redact secrets and personal or account identifiers first. The skill warns that a .env file is not automatically secure, so do not assume it is.

The skill is an auditor, not a deployment tool. It does not run terraform apply or kubectl apply. Test any hardened manifest in staging first to check for functional regressions. Keep a human in the loop for kernel-level merges.

• Obtain authorisation before sending private material to the model API.
• Redact secrets and account identifiers before sending any input.
• Keep GEMINI_API_KEY in CI/CD secrets for production use.
• Make any .env file owner-only and gitignored if the upstream code needs one, and never display its contents.
• Run the upstream entry point, python3 main.py, only after you have reviewed the checkout and accepted its network and cost effects.

Tips for getting useful results

Run the cost auditor before every infrastructure change, not after it has been applied. Use the findings as a strong signal for human review rather than an approval. If you use GitHub Actions, the skill lists CI/CD quality gating as a use case, but the output should not be the sole merge authority.

If a model alias that the skill or upstream code depends on no longer works, confirm the SDK and model combination you have installed rather than assuming the old alias still exists.

• Give kernel reviews at least 5 lines of context around each diff.
• Name the exact security rules you want, such as non-root or read-only root filesystem.
• Compare findings against the real plan or manifest before acting on them.
• Read the upstream README at the documentation link for the current entry point and dependencies.