The Real Reason AI Agent Skills Get Rejected: Permission Declaration Mismatch

An AI Agent Skill Rejected Twice

A developer submitted five AI Agent skills to a skill marketplace. Four went live within minutes, but one was rejected twice in a row — and the reason had nothing to do with the skill's quality.

The skill fetched real-time data via read-only JSON-RPC calls. It worked fine and came with tests. But the reviewer's rejection reason read: "The permissions declared by this skill are insufficient to support its described functionality. It claims to interact with blockchain RPC but has not declared any network tools or hosts."

In other words, the marketplace's security review mechanism automatically cross-references the capabilities described in SKILL.md against the tools/hosts listed in the permission declaration. The moment words like fetch, HTTP, API, or RPC appear in the documentation while the permission declaration contains no network tools — instant rejection, every time.

This type of problem is becoming a typical pain point in the AI Agent skill ecosystem. As Agent applications accelerate toward production, automated review for marketplace listings will only get stricter — and permission declarations happen to be the step developers most easily overlook.

Why This Mismatch Happens

The marketplace auto-detects permissions from the uploaded package. But auto-detection is fundamentally heuristic, and heuristics fail precisely where precision matters most — skills that use the network in a read-only, low-risk manner.

The failure mode is asymmetric:

• Under-declaring (skill uses the network, declaration omits it) → instant rejection, because the reviewer cannot verify what data leaves the user's machine
• Over-declaring (declaring a tool the skill never uses) → no problem, as long as the permission notes explain why it's declared defensively

This asymmetry means: when in doubt, declare more, then explain clearly in the notes field. Unfortunately, many developers default to a "least privilege" mindset, assuming fewer declarations are safer — only to get stuck at review.

The deeper issue is a systematic gap between security review logic and developer intuition. The reviewer's core concern is "what data leaves this machine," while the developer's focus is "does the skill work." That information gap is exactly what the permission declaration needs to bridge.

SKILL.md is the core description file in an AI Agent skill package, typically in Markdown format with Frontmatter. The Frontmatter section usually contains only two fields — name and description — declaring to the Agent "what this skill is called" and "when it should be loaded"; the body describes the skill's capabilities, workflow, input/output examples, and caveats. The marketplace's automated review system parses the semantic content of SKILL.md's body and cross-references it against the tools and hosts listed in the permission declaration: if network-related vocabulary appears in the body without a network declaration, it's judged as "declared permissions insufficient to support described functionality." SKILL.md is therefore not just a manual for the Agent and users — it's also the primary basis for the review system to determine whether permissions match.

The Five-Minute Fix

After multiple rejections, the developer distilled a set of pre-submission self-check steps:

Keyword-Scan Your SKILL.md

Search for these words: fetch, HTTP, API, RPC, webhook, endpoint, curl. If any appear where runtime behavior is described, you must declare the network tool. This takes only a few minutes but prevents the vast majority of automated rejections.

List All Runtime Hosts

RPC endpoints, API base URLs, payment providers — list them all. Documentation links don't count; only targets actually accessed at runtime do. This distinction is crucial because the reviewer tracks data flow, not which reference docs you cited.

Write the Notes Field Like You're Writing to an Auditor

One or two sentences explaining what the network access is for and what it is not for (no keys, no data writes, no transactions). This is the difference between the reviewer "guessing" and "confirming." A clear note can turn manual review into auto-approval.

Check the Reverse Direction Too

If the skill reads files, declare file_read. If it runs scripts, declare terminal. A mismatch in either direction triggers manual review — and manual review means longer waits and more uncertainty.

Resubmission Has a Trap: The Snapshot Mechanism

After fixing the permission declaration, the developer resubmitted through the admin panel and received the exact same rejection message minutes later. The reason: security screening targets the snapshot at submission time. Updating metadata afterward — even through the platform's own API — does not create a new snapshot.

The correct resubmission flow is:

1. Open the edit form for the existing listing (submitting a brand-new form gets rejected for duplicate name)
2. Use the "Replace skill ZIP — requires re-approval" option to re-upload the package, which creates a new snapshot
3. Confirm through the final review dialog to submit the snapshot for review

This snapshot mechanism is an invisible trap for developers unfamiliar with the platform's internal processes. It means the intuition of "changing it counts" doesn't hold here — you must trigger a full re-upload for the review system to see the change.

The snapshot mechanism refers to the platform making an immutable record of the SKILL.md, permission declaration, and ZIP contents at the moment of submission, with all subsequent review based on that snapshot. This means modifying metadata through the admin panel or platform API won't let the review system see new content, because that only modifies the listing's display information rather than regenerating the snapshot. Only re-uploading the package through the "Replace skill ZIP — requires re-approval" option creates a new snapshot and triggers review. The purpose of this design is to ensure the reviewed object matches what's actually listed, preventing developers from secretly modifying skill behavior after approval. Understanding this explains why "I changed the permission declaration but got the exact same rejection" — the review is always against the old snapshot.

Pre-Submission Self-Check List

The developer now runs through this checklist before every submission:

• Permission declaration covers every capability keyword in the documentation
• All runtime hosts declared, pure documentation domains excluded
• Permission notes explain the "why" and the "what not to do"
• The first sentence of the description answers "when should the Agent load this skill"
• Frontmatter contains only name and description, with no Markdown inside values
• Body structure is complete: when to use → what it does → how it works → example output → caveats
• No hardcoded keys; destructive operations explicitly opt-in
• Pricing within the reasonable range for the category

This checklist itself has been packaged into a skill — Agent Skill Publish Gate, a 7-gate static audit tool that pre-checks SKILL.md before submitting to any platform.

Frontmatter is the metadata block wrapped by --- at the top of a Markdown file. In SKILL.md, only two fields are typically allowed: name and description. The review system has strict format requirements for Frontmatter: values cannot contain Markdown syntax, or parsing may fail or be judged non-compliant. Additionally, the first sentence of description must answer "when should the Agent load this skill," because this directly affects whether the Agent can correctly route to the skill at runtime. The body structure should follow the sequence "when to use → what it does → how it works → example output → caveats," allowing both reviewers and users to quickly assess the skill's capability boundaries and security properties.

The Bigger Lesson

For developers delivering on the Agent toolchain this year, this experience points to a more fundamental realization: a skill that runs is not the same as a skill that ships.

Reviewers can only approve what they can verify, and verification starts with an honest, complete permission declaration. Rather than treating the permission declaration as administrative paperwork, think of it as a communication protocol with the reviewer — write it clearly, and everyone saves time.

Automated marketplace review will only become more sophisticated. Rejected today for permission declaration mismatch, you might be blocked tomorrow by finer-grained compliance requirements. Building a pre-submission self-check process in advance is far more efficient than backtracking after the fact.

Bring credentials, not promises.

Background

The Principle of Least Privilege is a classic practice in software security: a program should request only the minimum permissions necessary for its functionality, to minimize attack surface. But in the context of automated marketplace review, this principle conflicts with review logic. The reviewer's primary concern is "what data leaves the user's machine," not "does the skill work." If a skill accesses RPC read-only without declaring network permissions, the reviewer cannot verify data flow and can only reject outright. Conversely, declaring an extra tool that isn't actually used typically won't cause rejection, as long as the notes explain it's a defensive declaration. So in this specific scenario of marketplace listing, developers need to temporarily adjust "least privilege" to "verifiable complete declaration."