🛡️ Agent Skill Governance Auditor

Evidence-Based Control for the Agentic Action Era.
A governance layer that creates a "Safety Kernel" for autonomous agents.

---

🚨 The Problem

AI agents are entering the Action Era. They no longer just chat or suggest—they plan, decide, and execute.

But today's AI ecosystem has a fatal flaw:

• Skills are trusted by description.
• Execution happens without enforceable constraints.
• Decisions cannot be independently audited or replayed.
• Responsibility is unclear when autonomous actions fail.

This is not a model problem. It is a governance problem.

💡 The Solution

Agent Skill Governance is an audit-first control system that acts as a firewall for agent capabilities. It answers one question:

Should this agent be allowed to act—and under what constraints—based on the evidence?

Instead of prompting agents to "behave safely", we bind execution to auditable decisions.

---

✨ Key Features

1. 🧠 Autonomous Governance Reasoning

Using Google Gemini 2.5/3.0, the system performs a deep forensic audit of an agent's code/definition. It doesn't just look for bugs; it looks for governance gaps:

• Activation Risk: Does it auto-activate without consent?
• Responsibility Anchoring: Who is to blame if it fails?
• Context Boundaries: Does it ask for more data than it needs?

2. 🛡️ Immutable Platform Kernel

A set of "Kernel Rules" that cannot be overridden by users. Even if a user says "Allow All", the Kernel enforces safety floors for PII, Financial Access, and System IO.

3. 🧪 Red Team Adversarial Simulation

The system proactively generates "Hack" prompts to test if the agent skill can be tricked into privilege escalation or data exfiltration.

4. 🔧 Active Remediation Agent

Don't just reject unsafe code—fix it. The built-in agent rewrites the raw skill code to inject the missing runtime constraints identified during the audit.

5. 📦 Governance Lockfiles & CI/CD

Generates a cryptographic governance.lock file and CI/CD configurations. This allows you to gate deployment pipelines: No Audit = No Deploy.

---

🏗️ Architecture

This is a Full-Stack Application designed for resilience.

• Frontend: React 19, Vite, Tailwind CSS, Recharts.
  • Client-side Logic: Performs lightweight analysis and visualization.
  • Offline Mode: Works elegantly even if the backend is unreachable.
• AI Engine: Google GenAI SDK (@google/genai).
  • Models: gemini-3-pro-preview (Reasoning), gemini-3-flash-preview (Summarization), text-embedding-004 (Semantic Search).
• Backend (Optional for Demo): Node.js, Express, Prisma, SQLite.
  • Stores audit history, user profiles, and syncs governance artifacts.

---

🚀 Getting Started

Start building View your app in AI Studio: https://ai.studio/apps/drive/1dyMb7c0QEeLa8U1E6bUtfpmoySaZgRGe

Prerequisites

• Node.js 18+
• A Google Cloud Project with the Gemini API enabled.
• Get a Gemini API Key

Quick Start (Frontend Only / Demo Mode)

The app includes a robust "Demo Mode" that mocks the backend identity service, allowing you to test the core auditing features immediately.

1. Clone the repository

   git clone https://github.com/your-username/agent-skill-governance.git
   cd agent-skill-governance

2. Install Dependencies

   npm install

3. Configure Environment Create a .env.local file in the root directory:

   # .env.local
   # Required for the AI Auditor to function
   VITE_API_KEY=your_gemini_api_key_here
   
   # Optional: Point to backend if running locally
   VITE_API_URL=http://localhost:3000/api

4. Run the App

   npm run dev

   Open http://localhost:5173 in your browser.

---

🛠️ Full Stack Deployment (Optional)

To enable persistent history, user accounts, and team collaboration:

1. Setup Backend

   cd backend
   npm install
   
   # Create .env file for backend
   echo "DATABASE_URL='file:./dev.db'" > .env
   echo "JWT_SECRET='super-secret-key'" >> .env
   
   # Initialize Database
   npx prisma generate
   npx prisma db push
   
   # Run Server
   npm run dev

2. Connect Frontend Ensure your root .env.local points to the backend:

   VITE_API_URL=http://localhost:3000/api

---

📖 Usage Guide

1. Import Skill: Paste any Agent Skill (JSON, Python, TypeScript, or Markdown definition).
2. Audit: Click "Execute Audit". Watch the "Neural Governance Engine" analyze the topology.
3. Review:
   • Check the Enforcement Gate (Block/Allow).
   • View the Red Team Simulation results.
   • Analyze the Governance Gap.
4. Remediate: If blocked, click "Auto-Remediate" to have the agent write a safe wrapper for you.
5. Export: Go to the "Integration" tab to download the governance.lock file for your repo.

---

🏆 Hackathon Alignment

This project targets the Action Era of AI:

• ✅ Autonomous Agents: Designed for long-running, self-directed loops.
• ✅ Not just RAG: It reasons over logic and policy, not just text retrieval.
• ✅ System 2 Thinking: Uses Gemini's "Thinking" capabilities to produce signed chains of thought (thoughtProcess).
• ✅ Trust & Safety: Moves safety from "vibes" to "evidence".

---

📜 License

MIT License. Open for contribution.

"Autonomy without accountability is failure. Governance without execution is theater."