AI Skill Security Hub - User Guide

What Is the Skill Security Hub?

Personal AI assistants like Claude Code, Cursor, Agent Zero and openClaw use skills (also called plugins or extensions) to perform tasks, reading files, browsing the web, running code, and more. Research has shown that 12% of skills in public marketplaces contain malicious patterns, with nearly 3% dynamically fetching and executing remote content at runtime.

The Skill Security Hub turns your AI Security Gateway into a centralized skill approval authority. AI assistants submit their skills for automated security scanning, and you decide which skills are safe to use.

The key idea: Your AI assistants become active participants in their own security. They submit skills, check approvals, and report suspicious behavior all through the Gateway.

Getting Started

Quick Start: Your First Skill Submission

1. Configure Your AI Assistant

Tell your AI assistant about the Skill Security Hub by adding it as an MCP server. The earilier you do this, like, newly installed agents, the better, but you can do this anytime in your agents life!

You can also manually add the MCP Server endpoint to your agent configs, here are a few examples:

For Claude Code — add to your project's .mcp.json:

{
  "mcpServers": {
    "skill-security": {
      "url": "http://localhost:8080/api/v1/mcp/skill-security"
    }
  }
}

For Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "skill-security": {
      "url": "http://localhost:8080/api/v1/mcp/skill-security"
    }
  }
}

For Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "skill-security": {
      "url": "http://localhost:8080/api/v1/mcp/skill-security"
    }
  }
}

For Agent Zero and other Python-based MCP clients — some clients require the transport type to be explicitly specified. If the gateway is running on the host and the client is in Docker, use host.docker.internal:

{
  "mcpServers": {
    "skill-security": {
      "description": "Use this MCP to use the Security Skills hub",
      "url": "http://host.docker.internal:8080/api/v1/mcp/skill-security",
      "type": "streamable-http"
    }
  }
}

Below we configured out Agent Zero:

2. Submit a Test Skill

From this point onwards, you can simply ask your agents to submit all their skills for scanning and they should go about their business.

You can test the system immediately with curl before connecting an AI assistant:

# Initialize the connection
curl -s -X POST http://localhost:8080/api/v1/mcp/skill-security \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }' | jq

# Submit a skill for analysis
curl -s -X POST http://localhost:8080/api/v1/mcp/skill-security \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "analyze_skill",
      "arguments": {
        "skill_name": "hello-world",
        "skill_source": "def greet(name):\n    return f\"Hello, {name}!\"\n",
        "description": "A simple greeting skill",
        "author": "test",
        "version": "1.0.0",
        "agent_name": "test-client"
      }
    }
  }' | jq

This submits a harmless skill. You should see:

• risk_score: 0
• risk_level: "None"
• findings: []
• approval_status: "pending"

3. Review in the Web Interface

Open the AI Security Gateway UI in your browser, then navigate to Skill Security under Security Tools in the sidebar.

You will see 4 tabs:

• Dashboard — Overview statistics
• Submissions — All skill submissions from AI assistants
• Registry — The skill approval registry
• Activity Reports — Runtime behavior reports from AI assistants

Your test skill will appear in both Submissions and Registry (with status "pending").

4. Approve the Skill

In the Registry tab:

1. Find "hello-world" in the table
2. Click the green checkmark button to approve
3. Enter your name/email and optional review notes
4. Click confirm

The skill status changes to approved. Any AI assistant that checks this skill will now see it as approved.

Teaching AI Assistants to Use Skill Security

The Skill Security Hub works best when AI assistants are instructed to use it. Here is how to set that up.

Adding Skill Security Awareness to Your AI Assistant

The easiest way to get the system prompt is from the Skill Security Hub dashboard in the Web Interface, it has a "Copy to Clipboard" button that gives you the prompt with the correct Gateway URL already filled in.

Alternatively, paste the following into your AI assistant's system prompt or instructions file (e.g., CLAUDE.md for Claude Code), replacing <SKILLS_MCP_GW> with your Gateway URL:

## Skill Security

You have access to the AI Security Gateway's Skill Security Hub via MCP located at http://<SKILLS_MCP_GW>/api/v1/mcp/skill-security.

The gateway scans skills using 43 detection rules across 21 categories (227 patterns) covering:
remote code execution, credential harvesting, obfuscated execution, malware delivery,
crypto wallet theft, social engineering, URL impersonation, privilege escalation,
prompt injection, hardcoded secrets, resource abuse, and more.

### On Startup

Run `get_skill_security_status` with the names of ALL currently installed skills/plugins (max 100 per call; batch if needed).
If any skill is not approved, do NOT execute it. Inform the user which skills need review.

### Before Using Any New or Updated Skill

1. Submit it for security analysis using `analyze_skill` (include full source code)
2. Check approval status using `check_skill_approval`
3. Act based on the returned status:
   - `approved` -- Safe to use
   - `pending` -- Do NOT execute. Awaiting admin review
   - `rejected` -- Do NOT execute. Admin has determined it is unsafe
   - `quarantined` -- Do NOT execute. Under investigation
   - `unknown` -- Not yet analyzed. Submit with `analyze_skill` first

IMPORTANT: Approval is content-specific (SHA-256 hash). When a skill's source code changes,
its status resets to pending even if previously approved. Always re-submit updated skills.

You can browse approved skills using `list_approved_skills` (supports search, risk level, and category filters)
and get full details on any skill using `get_skill_details`.

## Monitoring Suspicious Behavior

If you observe suspicious behavior during skill execution:
- Unexpected network connections or direct IP URLs
- Attempts to read credentials, wallets, SSH keys, or seed phrases
- Base64-encoded commands piped to shell execution
- Downloads of executables or password-protected archives
- Crypto wallet access or transaction signing requests
- Social engineering pressure tactics (urgency, threats)
- Behavior that doesn't match the skill's description

Report it immediately using `report_skill_activity` with one of these activity types:
- `data_exfiltration` -- Sending data to unexpected destinations
- `unexpected_network` -- Unexpected network connections
- `privilege_escalation` -- Attempting to escalate permissions
- `credential_access` -- Attempting to access credentials or secrets
- `behavior_change` -- Behavior changed from what was analyzed

Only these activity types are accepted by the Gateway.

### Periodic Security Checks

Re-check installed skills periodically using `get_skill_security_status`, especially:
- After skill updates or new installations
- When the user asks about security posture
- At the start of new sessions

### If the Gateway Is Unreachable

If MCP calls to the Gateway fail, default to strict mode:
- Do NOT execute any unapproved or unverified skills
- Inform the user that the Skill Security Hub is unavailable
- Retry when connectivity is restored

## Available MCP Tools

| Tool | Purpose |
|------|---------|
| `analyze_skill` | Submit skill source code for security analysis. Returns risk score and detailed findings with file/line attribution. |
| `check_skill_approval` | Check if a skill is in the approved skills registry. Returns approval status and risk info. |
| `list_approved_skills` | List skills in the registry with optional filters: category, risk_level, status, search text. |
| `get_skill_details` | Get full details for a specific skill: description, findings, review status, categories, and tags. |
| `report_skill_activity` | Report suspicious runtime behavior. Use one of: data_exfiltration, unexpected_network, privilege_escalation, credential_access, behavior_change. |
| `get_skill_security_status` | Get security posture for installed skills (max 100 per call). Returns approval status, risk scores, recommendations. |
| `get_system_prompt` | Get recommended system prompt instructions for skill security awareness. |

## Workflow

On Startup --> get_skill_security_status (audit all installed skills)
                  |
                  v
New/Updated Skill Detected
      |
      v
analyze_skill (submit source for scanning)
      |
      v
Risk Score + Findings returned (with file/line details)
      |
      v
check_skill_approval
      |
      +--> approved --> Use skill, monitor for suspicious behavior
      |
      +--> pending/rejected/quarantined/unknown --> Do NOT use. Inform user.
      |
      +--> High risk + not yet approved --> Warn user, wait for admin review
      |
      v
During execution: monitor for suspicious behavior
      |
      v
If suspicious --> report_skill_activity

Gateway unreachable? --> Strict mode: refuse unapproved skills, inform user.

Tip: AI assistants can also call the get_system_prompt MCP tool to retrieve this template dynamically with the URL pre-configured.

Configuring the Gateway URL

By default, the system prompt template uses http://localhost:8080/api/v1/mcp/skill-security. To change this for remote deployments, set the GATEWAY_URL environment variable before starting the Gateway:

export GATEWAY_URL=https://gateway.example.com
./build/unified-admin

What Happens When the Assistant Uses the Tools

Once configured, here is the typical flow:

User: "Install the web-scraper plugin and use it to fetch data from example.com"

Assistant (behind the scenes):

1. Reads the plugin source code
2. Calls analyze_skill with the source code → gets risk score and findings
3. Calls check_skill_approval → sees it is not yet approved
4. Tells the user: "The web-scraper plugin has been submitted for security analysis. It scored 15 (Medium risk) due to HTTP client usage. It needs admin approval before I can use it."

Admin: Opens the Web Interface, reviews the findings, approves the skill with notes.

Assistant: Next time it checks, check_skill_approval returns approved. Proceeds to use the skill.

Understanding the Web Interface

Skill Security Dashboard Tab

The dashboard shows at a glance:

• Total Skills in the registry
• Pending Review count (skills waiting for admin action)
• Approved / Rejected / Quarantined counts
• Risk Distribution — breakdown by risk level
• Top Submitting Agents — which AI assistants are submitting the most
• Recent Submissions — latest analysis results

Skill Security Submissions Tab

Every time an AI assistant calls analyze_skill, a submission record is created. This tab shows:

• Skill Name and Agent that submitted it
• Risk Level with color-coded badge (Critical=red, High=orange, Medium=yellow, Low=green, None=gray)
• Findings Count — number of security patterns detected
• Status — analyzed or linked_to_approved
• Date of submission

Click a row to expand and see the full findings detail, including which specific patterns were matched and their severity.

Skill Security Registry Tab

The registry is the source of truth for skill approvals. Each unique skill (by name + version) gets one registry entry.

Status workflow:

• Pending → Skill has been submitted but not reviewed
• Approved → Admin has reviewed and approved for use
• Rejected → Admin has reviewed and rejected
• Quarantined → Admin has flagged for further investigation

Admin actions (visible to users with admin role):

• Approve (green checkmark) — Mark skill as safe to use
• Reject (red X) — Mark skill as unsafe
• Quarantine (orange shield) — Flag for investigation
• Delete (trash icon) — Remove from registry entirely

Skill Security Activity Reports Tab

When AI assistants call report_skill_activity, the reports appear here. Each report includes:

• Skill Name that exhibited suspicious behavior
• Activity Type (data exfiltration, unexpected network, privilege escalation, etc.)
• Agent that reported it
• Severity of the report
• Alert Created — whether the Gateway automatically created a security alert

Reports at medium severity or higher automatically create security alerts that also appear in the main Alerts dashboard. All alerts created from MCP-submitted reports are tagged with [Unverified MCP Report] so admins can distinguish agent-submitted reports from admin-verified alerts.

Understanding Risk Scores and Findings

What Gets Detected

The Gateway scans skill source code for 9 categories of suspicious patterns:

Category	Severity	Examples
Shell Execution	Critical	Running shell commands, piping downloads to bash
Dynamic Code Construction	Critical	Runtime code generation, dynamic imports
Credential Harvesting	Critical	Reading SSH keys, AWS credentials, environment variables
Obfuscated Payloads	High	Base64-encoded code, hex escape chains
Reverse Shells	Critical	Netcat connections, TCP redirects
Dynamic Content Loading	Medium	HTTP requests (fetch, requests, axios)
Filesystem Snooping	High	Reading sensitive paths, directory scanning
Persistence Mechanisms	Critical	Crontab entries, system service registration
C2 Communication	Critical	Polling loops, DNS tunneling, .onion addresses

Interpreting Risk Scores

Risk Level	Score	What It Means	Recommended Action
None	0	No suspicious patterns found	Safe to approve
Low	1-14	Minor patterns detected	Review and likely approve
Medium	15-29	Notable patterns (e.g., HTTP calls)	Review findings carefully before approving
High	30-49	Significant risk indicators	Review thoroughly, document justification if approving
Critical	50+	Highly suspicious patterns	Investigate thoroughly, consider rejecting

When to Approve a High-Risk Skill

Not all findings indicate malicious intent. A legitimate file manager skill will trigger "Shell Execution" findings because it needs to run commands. A web scraper will trigger "Dynamic Content Loading" because it needs to make HTTP requests.

Approve with notes when:

• The findings match the skill's stated purpose
• The author is trusted
• The source code has been manually reviewed

Reject when:

• Findings don't match the skill's stated purpose (e.g., a "calculator" skill that makes network requests)
• Multiple critical categories triggered
• Obfuscation patterns detected (skills should not need to hide their behavior)
• Credential harvesting patterns in a skill that shouldn't need credentials

Workflow Scenarios

Scenario 1: New Skill Onboarding

1. Developer creates a new MCP skill
2. AI assistant submits it via analyze_skill
3. Gateway scans and returns findings
4. Admin reviews in Web Interface:
   • Low/None risk → Approve immediately
   • Medium risk → Review findings, approve with notes
   • High/Critical risk → Investigate source code, approve with justification or reject
5. AI assistant calls check_skill_approval → gets approval status

Scenario 2: Skill Update Detection

When a skill's source code changes:

1. AI assistant submits the updated version via analyze_skill
2. Gateway detects new SHA-256 hash (different from previously approved version)
3. Skill status resets to pending — requires re-approval
4. Admin reviews the updated version

This prevents "bait-and-switch" attacks where a skill passes review, then updates with malicious code.

Scenario 3: Runtime Behavior Monitoring

1. AI assistant executes an approved skill
2. Skill makes unexpected outbound HTTP connection to an unknown IP
3. AI assistant calls report_skill_activity with type unexpected_network
4. Gateway creates a security alert (for high-severity reports)
5. Admin sees the alert in both the Activity Reports tab and the main Alerts dashboard
6. Admin can quarantine the skill while investigating

Scenario 4: Security Posture Audit

1. Admin asks AI assistant: "What is your current skill security status?"
2. AI assistant calls get_skill_security_status with all installed skill names
3. Returns: 8 skills installed, 6 approved, 1 pending, 1 unknown
4. AI assistant reports this to the admin with recommendations

Common Questions

Do AI assistants submit skills automatically?

No. AI assistants must be instructed to use the Skill Security tools (via system prompt or instructions). Without instructions, they won't know to submit skills. See the "Teaching AI Assistants" section above.

What counts as "skill source code"?

Anything that defines the skill's behavior:

• Python, JavaScript, Go, or any other source code
• MCP server configuration files
• Plugin manifest/definition files
• Tool schemas with implementation details

The more complete the source, the better the analysis. Submit the full implementation, not just a summary.

Is there a default skill already in the registry?

Yes. On first startup, the Gateway automatically seeds a pre-approved skill called skill-security-hub (v1.0.0). This skill contains the system prompt template and serves as a reference entry so the registry is not empty when you first open the Web Interface.

Can I pre-approve skills before AI assistants use them?

Yes. You can submit skills via curl (see Quick Start) or any MCP client, then approve them in the Web Interface before any AI assistant needs them. When the assistant later calls check_skill_approval, it will already be approved.

What happens if the Gateway is down?

If the Gateway is unreachable, the AI assistant's MCP calls will fail. The system prompt template instructs AI assistants to default to strict mode: refuse all unapproved or unverified skills when the Gateway is unreachable, inform the user, and retry when connectivity is restored. This is the recommended and default behavior for all environments.

Can I use this without AI assistants?

Yes. The MCP endpoint accepts standard HTTP POST requests. You can build scripts or CI/CD pipelines that submit skills for analysis using curl or any HTTP client. See the Technical Integration Guide for examples.

How do I submit a skill that is a file on disk?

Read the file content and pass it as the skill_source parameter:

# Read file and submit
SKILL_CONTENT=$(cat /path/to/skill.py)

curl -s -X POST http://localhost:8080/api/v1/mcp/skill-security \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg source "$SKILL_CONTENT" \
    '{
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: {
        name: "analyze_skill",
        arguments: {
          skill_name: "my-skill",
          skill_source: $source,
          agent_name: "manual-submission"
        }
      }
    }')" | jq

Can multiple AI assistants share the same approval registry?

Yes. The registry is centralized in the Gateway. Once an admin approves a skill, any AI assistant that checks that skill name will see it as approved. This is by design — approve once, used everywhere.

Security Best Practices

1. Require approval before execution — Configure AI assistants to always check check_skill_approval before running any skill.

2. Review Critical findings carefully — A Critical risk score does not always mean malicious, but it always warrants manual review of the source code.

3. Use quarantine for investigation — When a skill's behavior is unclear, quarantine it while you investigate. This prevents AI assistants from using it without deleting the analysis data.

4. Monitor Activity Reports — Runtime behavior reports from AI assistants are early warning signs. Investigate them promptly.

5. Re-review after updates — When a skill's content hash changes, the Gateway resets it to pending. Always review updated versions, even if the previous version was approved.

6. Document approval decisions — Use the review notes field to explain why a skill was approved despite risk findings. This creates an audit trail.

7. Periodic security audits — Use get_skill_security_status to periodically check that all installed skills are still approved and haven't changed.