Agentic Development

How to review and secure AI agent skills

AI agent skills are reusable instruction packages that teach coding agents how to perform a specific task reliably, such as configuring an API security scan, deploying a service, or creating a pull request. A well-built skill gives an agent clear activation criteria, safe operating boundaries, and r

MMichael SwindellAugust 17, 202616 min read

AI agent skill security diagram showing progressive disclosure from low-privilege entry layer through validation gate to high-privilege reference layer

AI agent skills are reusable instruction packages that teach coding agents how to perform a specific task reliably, such as configuring an API security scan, deploying a service, or creating a pull request. A well-built skill gives an agent clear activation criteria, safe operating boundaries, and reference material without overwhelming its context window. The challenge is that skills are often created informally at the end of a successful session, then shared before anyone has reviewed their quality or security. Teams need a repeatable way to evaluate routing, specificity, progressive disclosure, and risk. An agent-first control plane helps keep those skills connected to project intent, verification, and accountable delivery work.

At a Glance

Good agent skills are concise at entry, detailed on demand, and reviewed like production automation.

Start with routing: A skill must clearly state what it does, when it applies, and when a related skill should be used instead.
Use progressive disclosure: Keep the main SKILL.md focused, then move deep implementation details into referenced files.
Review quality: Evaluate skills against a consistent rubric instead of relying only on whether one agent run happened to succeed.
Scan for risk: Treat third-party and internally written skills as potential sources of unsafe instructions, prompt injection, or excessive access.
Standardize shared skills: Personal skills can remain flexible, but production, deployment, and security workflows need approved ownership and checks.

What makes an AI agent skill useful instead of just another prompt?

An AI agent skill bridges the gap between unstructured prompts and managed software automation. While a standard prompt instructs an agent for a single turn, a skill packages a reusable workflow with clear activation criteria, safe boundaries, and references. Teams transitioning from casual use to production engineering must treat these files as code assets, moving past informal sharing to established validation rules.

The challenge is that unchecked skill accumulation causes routing friction and context bloat. If an agent loads too many long instruction files, it risks missing critical parameters. Managing this boundary requires strict routing, specific activation triggers, and an understanding of the architectural principles of agent loop context compaction to keep executions clean.

Why should teams review skills against a written rubric?

A written rubric makes skill quality measurable and reproducible. Instead of declaring a skill useful because a single test run succeeded, a rubric evaluates structural properties: routing clarity, scope constraints, and permission boundaries. Running automated LLM-as-judge evaluations against this rubric ensures every new skill or update is scored objectively before it enters the team's shared directory.

To implement this, teams can deploy an LLM-as-judge pipeline that parses a proposed SKILL.md and its references. A practical evaluation prompt should enforce multi-point grading across key criteria. For example:

[You are an expert AI Agent Systems Auditor. Evaluate the following SKILL.md file and its referenced files against these criteria. Rate each from 1-5 and provide specific reasoning:

Routing & Activation: Does the file define exactly when the agent must activate this skill and when it must NOT (disambiguation)?
Principle of Least Privilege: Are the tools and resource scopes restricted to the minimum required for this specific task?
Progressive Disclosure: Are high-privilege credentials or complex environment variables isolated into referenced files rather than the main entry point?

Return your evaluation in JSON format with "scores" and "recommendations" keys.]

This automated assessment produces a diagnostic signal. For instance, in one API configuration skill review, the initial score was 87 percent. While it had clear API routing, it stored high-privilege authentication targets inline. Moving those targets to isolated references raised the score to 90 percent and limited the runtime blast radius. Standardizing this scoring mechanism prevents subjective evaluations from introducing brittle workflows.

A practical skill-review checklist

Activation: Does the description tell the agent exactly when to use this skill?
Disambiguation: Does it explain when to use a related skill instead?
Specificity: Are the steps concrete enough to act on without guessing?
Conciseness: Does the entry file avoid turning into a manual for every edge case?
Progressive disclosure: Are high-privilege commands and detailed parameters isolated into references?
Examples: Are common inputs, authentication paths, and expected outcomes actionable?
Safety: Does the skill restrict risky actions and identify necessary review points?
Verification: Does it define how the agent or human confirms the work succeeded?

Anthropic's official documentation for agent skills emphasizes reusable, task-specific instructions and supporting resources. That is a useful starting point, but teams should adapt any rubric to their tools, repositories, environments, and risk tolerance.

How does progressive disclosure enforce security and privilege isolation?

In secure agentic environments, progressive disclosure is more than a way to save context tokens; it is a mechanism for privilege isolation. By decoupling the main activation rules in SKILL.md from detailed sub-tasks, teams can control exactly when an agent gains access to high-privilege parameters, sensitive API endpoints, or write-access tools.

When an agent first evaluates a repository, it should only load the lightweight SKILL.md. This main file specifies the routing rules and the minimum baseline permissions required. High-privilege actions—such as rotating an API key, executing a destructive database script, or modifying production infrastructure—are stored in separate, referenced files. The agent is instructed to read these references only after it has successfully passed intermediate validation gates in the primary workflow.

This layered architecture minimizes the risk of indirect prompt injection:

Entry layer (Low-Privilege): The SKILL.md file defines basic routing and read-only discovery steps. The agent operates in a restricted environment with minimal capabilities.
Validation gate: The agent must programmatically verify its inputs (e.g., matching a strict regex pattern or checking a signed token) before progressing.
Reference layer (High-Privilege): If validation succeeds, the agent dynamically requests the reference files containing target credentials, write-capable tools, or administrative commands.

By enforcing this structure, an injection attack in the initial ingestion phase is blocked from immediately exploiting write-level access. If the agent fails to pass the intermediate validation steps defined in the entry file, it never retrieves the high-privilege reference files, successfully isolating the threat.

Give coding agents project context, not isolated instructions.

Levr connects issues, acceptance criteria, tests, workflow gates, and attributed work so skills operate within a visible delivery process rather than outside it.

Explore Levr’s agentic workflow

How should teams separate personal skills from shared skills?

Teams should allow personal skills for individual productivity while applying stronger ownership, review, and security controls to shared skills. Any skill used for deployment, production changes, security operations, or cross-team workflows should be treated as managed automation rather than private prompt history.

Personal skills are useful because developers naturally discover repeatable workflows during sessions with coding agents. Saving that workflow can reduce repetition and preserve hard-won context. The risk begins when a personal artifact becomes a team dependency without documentation, review, or a clear maintainer.

A practical maturity model looks like this:

Personal: One developer maintains a skill for local, low-risk work.
Team-shared: A repository contains skills for common engineering tasks, with pull request review and discoverable ownership.
Platform-managed: A platform or security team publishes approved skills for privileged operations, such as deployment or production access.

Production-oriented skills deserve extra scrutiny because they shape how an agent handles credentials, environments, and write-capable tools. A centrally published deployment skill can encode approved quality and security requirements. In contrast, dozens of independently written deployment skills make it much harder to know what automation is actually doing.

Teams using Levr’s agent-first project features can connect shared agent work to structured acceptance criteria, workflow states, test results, and an attributed activity trail. That does not replace a skill review process, but it gives engineering managers a clearer view of where skills are being used and what they changed.

What security risks can poorly written agent skills introduce?

Poorly written agent skills can introduce unsafe instructions, prompt injection exposure, overly broad access, and unreviewed third-party behavior. Because skills directly influence how agents interpret raw text and utilize platform tools, they must be assessed with the same scrutiny applied to third-party packages, scripts, and CI/CD pipelines. An unvetted skill file is a primary target for malicious exploits.

Specifically, bad actors can exploit vulnerabilities via unreviewed files, demonstrating how malicious SKILL.md files can compromise AI coding agents by establishing silent data exfiltration channels or executing unauthorized shell scripts. To prevent these vectors, teams should pair strict static checks with robust execution containment, utilizing infrastructure-level AI agent sandboxing and Zero-Trust controls to ensure that even a compromised model cannot escape the runtime container or access the host system.

Key risk categories include:

Prompt injection: Instructions from untrusted content may attempt to override the skill’s intended behavior.
Unsafe tool usage: A skill may guide an agent to run commands, modify systems, or access data without appropriate boundaries.
Credential exposure: Detailed examples can encourage insecure handling of tokens, keys, or environment variables.
Overbroad permissions: A task may require read access but the skill assumes write access to a repository or production system.
Untrusted dependencies: Third-party skills may pull in tools or instructions that have not been reviewed.

Snyk’s Agent Scan repository provides a tool for scanning agent-related files and skills for security concerns. This is important because a skill repository should not be trusted simply because it is convenient or widely shared.

Security guidance for agents is still evolving. No scanner or prompt policy can prove that a skill is safe in every context. The right approach combines scanning with least privilege, sandboxing, review requirements, and clear limits on what an agent may change.

How can you add skill checks to a pull request workflow?

Vetting skills requires adding automated checks directly into your pull request pipeline. When a developer or agent proposes changes to a SKILL.md or any of its references, the CI pipeline must intercept the PR, run quality rubrics, scan for vulnerabilities, and block merges until human owners sign off. This prevents unreviewed configurations from silently degrading team-wide automation.

Using standard workflow templates—similar to those detailed in the Claude Code skills workflow guide—you can define deterministic validation steps. Below is a sample GitHub Actions YAML workflow that automates this process:

name: AI Agent Skill Review Gate

on:

pull_request:

paths:

- '**/SKILL.md'

- '.agent-skills/**'

jobs:

validate-skill:

runs-on: ubuntu-latest

steps:

- name: Checkout Code

uses: actions/checkout@v4

- name: Run Snyk Agent Scan

run: |

npm install -g @snyk/agent-scan

snyk-agent-scan lint --path ./.agent-skills/

- name: Run LLM-as-Judge Quality Rubric

env:

OPENAI_API_KEY: ${{ secrets.JUDGE_LLM_KEY }}

run: |

node ./scripts/evaluate-skill-rubric.js --pr-diff

If either the security scan or the quality rubric score falls below your team's threshold (e.g., 90%), the CI job fails, blocking the PR from merging. Levr supports this pattern directly — every skill invocation, tool call, and review decision is attributed and timestamped in one audit trail, so a skill's provenance is never separated from its usage. This gives engineering managers and security teams complete visibility into when a skill changed, who approved it, and exactly how coding agents have applied it across your codebase.

Governance You Can See: The Levr Dashboard

The Levr Dashboard brings real-time observability to your team's AI agent skills, turning complex command logs into a clear governance trail. It maps every skill execution and automated PR-gate run directly to an active rubric score, giving engineers a visual dashboard of active automation risks. Teams can instantly identify which skills are passing security standards, which runs require human review, and who authorized the latest workflow modifications.

Agentic Software Development | Control Plane | Manual & Automatic Verification Issue Tracking |Levr

The Levr Dashboard maps every skill execution to its rubric score, giving teams a live view of which skills pass review and which need attention.

What mistakes should you avoid when improving agent skills?

The biggest mistakes are treating a score as proof of quality, packing all details into one file, publishing privileged skills without ownership, and assuming an automated fix is safe. Skill improvement works best as an iterative engineering practice, not a one-click documentation exercise.

Chasing a perfect score: A benchmark can highlight useful improvements, but it cannot fully model your system, users, or security requirements.
Over-compressing instructions: Conciseness should not remove safety boundaries, activation conditions, or verification requirements.
Creating ambiguous siblings: Similar skills must explain their separate use cases or agents will choose inconsistently.
Copying skills without scanning them: Third-party content needs provenance, review, and security checks.
Confusing completion with verification: A skill should describe proof that the change, scan, test, or configuration actually worked.
Leaving shared skills ownerless: Someone must be accountable for updates, regressions, and retirement.

The goal is not to eliminate every personal skill or prevent experimentation. It is to create a boundary between low-risk individual workflow improvements and managed automation that can affect a codebase, pipeline, customer environment, or production system.

Technical Deep Dive FAQ

What is an AI agent skill?

An AI agent skill is a structured package of instructions, activation parameters, and supporting files that guides an agent through a specific task. Unlike simple prompts, skills are designed for repeatable execution across different environments and tasks, acting as managed operational assets within a team’s codebase.

What is a SKILL.md file?

A SKILL.md file is commonly used as the main entry point for an agent skill. It typically contains the skill’s name, purpose, activation guidance, core workflow, guardrails, and references to supporting documents. The main file should help an agent decide whether the skill is relevant before loading excessive detail. Large examples, alternative configuration paths, and specialized implementation notes are often better placed in linked reference files so the agent can retrieve them only when necessary.

What does progressive disclosure mean for coding agent skills?

Progressive disclosure means revealing instructions in layers rather than loading every possible detail at once. The skill’s main file contains routing and the standard path, while linked references contain specialized details such as authentication variants, host-specific commands, and troubleshooting. This keeps the initial context focused and reduces the chance that an agent misses important instructions in a long file. It also helps preserve the agent’s context capacity for the repository, issue, tests, and current task.

How do I know whether two skills overlap too much?

Two skills overlap too much when an agent cannot reliably decide which one to activate from their names and descriptions. Review each skill’s purpose, inputs, exclusions, and expected output. If both could apply to the same request, add explicit disambiguation or merge them. For example, web target configuration and API target configuration can remain separate if each skill clearly identifies the target type it supports and points to the other skill when the request falls outside its scope.

Should every agent skill include security instructions?

Every skill should include the safety boundaries relevant to its task, but not every file needs a generic security lecture. A skill that reads documentation has different risks from a skill that deploys an application or changes cloud configuration. Include required permission limits, handling rules for secrets, confirmation points for destructive actions, and escalation conditions. For privileged workflows, pair instructions with technical controls such as least-privilege credentials, sandboxed execution, and pull request or human approval gates.

How should I review an automated skill fix?

Review an automated skill fix as you would review an automation change. Start with the diff and verify that required instructions were not removed or weakened. Confirm that links to new reference files are correct and that the core workflow still works without loading unrelated content. Test representative tasks, including common paths and meaningful edge cases. If the skill controls privileged actions, have the appropriate service, platform, or security owner approve the update before it becomes available to other agents.

Can I use AI agent skills in CI/CD pipelines?

Yes. Teams can run checks for changed skills as part of CI/CD, particularly when skills are stored in version control. Useful checks include quality reviews, security scans, link validation, schema validation, and tests that exercise representative agent tasks. The pipeline should distinguish low-risk documentation edits from updates that alter deployment, production, or security behavior. For high-risk skills, automation should report findings and block unapproved changes rather than granting agents unrestricted authority to modify the environment.

How should engineering managers govern shared agent skills?

Engineering managers should create lightweight ownership, review, and observability rules for shared skills. Maintain an inventory of approved skills, identify owners, separate personal from platform-managed workflows, and define which changes require security or platform review. Measure whether skills create repeated value, reduce rework, or cause failures that need correction. A shared control plane can also connect skill-driven work to issues, acceptance criteria, tests, pull requests, and activity history, making accountability visible across both human and agent contributors.

Can a high review score guarantee that a skill is secure?

No. A high review score indicates alignment with the review rubric, not proof that a skill is secure in every environment. A skill may be clear, concise, and well structured while still having access to unsafe tools or being exposed to malicious external content. Use quality scoring as one layer of assurance alongside security scanning, permission controls, sandboxing, source review, test evidence, and human approval. The more privileged the task, the more independent controls it should require.

When should a team retire or replace an agent skill?

Retire or replace a skill when its underlying tools, APIs, deployment process, or security assumptions change. Also remove skills that are rarely used, overlap with better maintained alternatives, create repeated routing mistakes, or cannot meet current ownership requirements. Keeping outdated skills available can be worse than having no skill because agents may confidently follow stale instructions. Version control, review history, and regular audits make it easier to identify skills that should be updated, consolidated, or removed from team discovery.

Key Takeaways

Reliable agent skills are operational assets, not disposable prompt fragments.

Build skills like you build other shared engineering automation.

Structure matters: Keep activation and core steps in SKILL.md, then use references for deep, conditional detail.
Review is repeatable: Use a written rubric to assess routing, clarity, specificity, conciseness, and verification.
Security is continuous: Scan skills, limit permissions, review third-party content, and protect privileged workflows with gates.
Ownership scales trust: Let developers experiment personally, while platform-managed skills govern shared and production-impacting work.

A skill is valuable when an agent can select it correctly, follow it safely, and produce evidence that the intended work is complete.