Skill Risk Filter

Relevant source files

The following files were used as context for generating this wiki page:

• bundled-skills/skill-scanner/SKILL.md
• bundled-skills/skill-writer/SKILL.md
• bundled-skills/codebase-audit-pre-push/SKILL.md
• bundled-skills/skill-creator-ms/SKILL.md
• bundled-skills/skill-developer/SKILL.md
• src/skill-pointer/skill-risk-filter.ts
• src/skill-pointer/risk-level.ts
• src/__tests__/skill-risk-filter.test.ts

The Skill Risk Filter is a core security and quality control mechanism designed to evaluate and categorize agent skills based on their potential impact on the system. It serves as a gatekeeper during the skill adoption and execution lifecycle, ensuring that skills with high-risk capabilities—such as file system modifications, credential access, or external network calls—are identified and subjected to appropriate enforcement levels.

This system operates by analyzing the metadata and behavioral patterns of a skill, assigning a specific risk level that dictates whether the skill can be auto-activated, requires manual approval, or should be blocked entirely. By integrating with the project's Skill Developer Guide, the filter maintains system integrity while allowing for the progressive disclosure of advanced capabilities.

Sources: bundled-skills/skill-scanner/SKILL.md, bundled-skills/skill-developer/SKILL.md

Core Risk Architecture

The architecture of the risk filter is built around static analysis and behavioral profiling. It evaluates skills across multiple dimensions, including tool permissions, prompt injection patterns, and script safety.

Risk Level Categorization

The system utilizes a tiered risk model to classify skills. These levels are defined based on the tools and permissions requested by the skill in its YAML frontmatter.

Risk Level	Criteria	Enforcement Action
Safe / Low	Read-only operations, standard analysis tools (Grep, Glob).	Auto-activation allowed.
Medium	Use of Bash for bundled scripts, limited file writes.	Suggestion/Warning injected.
High	Full file system access, network calls, or credential reading.	Manual approval or Block.
Critical	Confirmed malicious intent or dangerous prompt injection.	Strict Block/Rejection.

Sources: bundled-skills/skill-scanner/SKILL.md, bundled-skills/skill-developer/SKILL.md

Assessment Workflow

The following diagram illustrates the logical flow of a skill being processed by the risk filter during discovery or pre-execution.

The workflow prioritizes identifying high-privilege tools (e.g., Bash, Write, WebFetch) early in the process to set baseline risk tiers.
Sources: bundled-skills/skill-scanner/SKILL.md

Filtering Dimensions

The filter evaluates skills through specific "lenses" to determine their final risk score.

Permission Analysis

The filter examines the allowed-tools field in the skill's metadata. A skill requesting Bash without a bundled script in its scripts/ directory is flagged as a "justification mismatch."

• Low Risk Profile: Read, Grep, Glob
• Medium Risk Profile: Read, Grep, Glob, Bash (with local script)
• High Risk Profile: Read, Grep, Glob, Bash, Write, Edit, WebFetch, Task

Sources: bundled-skills/skill-scanner/SKILL.md

Behavioral Analysis

The filter looks for "Scope Creep"—instructions that exceed the skill's stated purpose. For instance, a skill described as a "Markdown Formatter" that attempts to read ~/.ssh or environment variables is immediately flagged.

The Behavioral Analysis phase ensures that a skill's instructions align strictly with its metadata description.
Sources: bundled-skills/skill-scanner/SKILL.md

Enforcement Mechanisms

Based on the risk level determined by the filter, different enforcement mechanisms are applied to the agent's runtime.

Block vs. Suggest

• Block (Critical/High Risk): Utilized for "Guardrail Skills" where data integrity or security is at stake. The filter prevents tool execution (Exit Code 2) until the risk is mitigated.
• Suggest (Medium/Low Risk): Utilized for "Domain Skills." The filter injects context reminders into the prompt without stopping the workflow.

Sources: bundled-skills/skill-developer/SKILL.md

Static Analysis Patterns

The filter uses a suite of patterns to detect dangerous code in bundled scripts:

• Data Exfiltration: Detection of socket connections or curl calls to untrusted domains.
• Credential Theft: Scanning for attempts to read .env, .pem, or credentials.json.
• Dangerous Execution: Identifying eval() or exec() calls with dynamic, unvalidated input.

Sources: bundled-skills/skill-scanner/SKILL.md, bundled-skills/codebase-audit-pre-push/SKILL.md

Implementation Details

The Risk Filter is implemented as part of the skill-pointer module, specifically utilizing the logic found in skill-risk-filter.ts.

Technical Configuration

Skills are validated against a schema that enforces specific metadata requirements to facilitate risk filtering.

# Example of a High-Risk Skill Metadata
name: remote-deploy-tool
description: Use when deploying to production.
risk: high # Explicitly categorized
allowed-tools:
  - Bash
  - WebFetch
  - Write

Sources: bundled-skills/skill-creator-ms/SKILL.md, bundled-skills/skill-scanner/SKILL.md

Summary

The Skill Risk Filter is an essential security layer that categorizes agent capabilities into actionable risk tiers. By combining static permission checks with behavioral analysis of skill instructions and scripts, it prevents malicious or poorly scoped skills from compromising the system. This allows developers to safely extend agent functionality while maintaining strict guardrails on critical system resources.