Architectural Analysis, Cross-Platform Interoperability, and the Tool Ecosystem.
The evolution of artificial intelligence systems in software development has marked a transition from basic autocomplete tools to fully autonomous agentic platforms. Modern AI coding agents can independently plan architectures, navigate complex file systems, execute terminal commands, and orchestrate project deployments. However, despite the computational power of underlying large language models (LLMs), their application frequently encounters a problem known as “distributional convergence.” The essence of this phenomenon is that models trained on vast arrays of averaged data tend to generate statistically safe but unremarkable and standardized solutions, lacking specific domain expertise or a unique design signature.
To overcome this fundamental limitation, the industry developed the concept of modular extensions known as AI skills (Agent Skills). This report presents a comprehensive analysis of the architecture of AI skills, their interoperability across leading platforms such as Claude Code, OpenAI Codex, and Google Antigravity, as well as a detailed review of the best tools and generators designed to create, manage, and audit these procedural modules.
The Fundamental Architecture of AI Skills
AI skills are lightweight, open packaging formats for procedural knowledge, specialized workflows, and tools that dynamically extend the capabilities of AI agents. Unlike classic system prompts, which are hardcoded into the application’s source code or API configurations, skills exist as autonomous directories in the developer’s file system and are managed via standard version control systems.
The philosophy behind skills lies in decoupling the agent’s core capabilities (acting as the “operating system”) from domain expertise (acting as installable “applications”). Skills serve as corporate guidelines or playbooks, teaching the agent how to think, which algorithms to apply, what data formats to return, and which typical mistakes to avoid when working in a specific domain.
Standardized Directory Structure
To ensure universality and compatibility, the Agent Skills open standard was developed (originally created by Anthropic and later handed over to the community, published at agentskills.io). The specification strictly regulates the skill directory architecture, allowing agents to load additional resources only when they are actually needed.
Structure Element
Status
Purpose and Content
SKILL.md
Required
The central file containing metadata (YAML) and instructions (Markdown) that define the skill’s logic.
scripts/
Optional
Executable files (Bash, Python, JavaScript) that the agent can invoke locally. Scripts must gracefully handle errors and edge cases.
references/
Optional
Deep technical documentation, coding standards, and corporate business logic (e.g., finance.md, FORMS.md) that the agent can consult when necessary.
assets/
Optional
Static resources such as document templates, database schemas, configuration files, and images.
examples/
Optional
Examples of baseline inputs and outputs, helping the agent adapt to the expected data format.
Anatomy of the SKILL.md File and Metadata
The SKILL.md file is functionally divided into two critical sections: a YAML metadata block (frontmatter) and the instruction body in Markdown format.
The metadata block is bounded by --- markers and acts as an identifier and router. The specification imposes strict constraints on the fields within this block to ensure predictable parsing by all client applications. The name field is mandatory, limited to 1–64 characters, accepts only lowercase letters, numbers, and hyphens (with no consecutive hyphens), and must exactly match the name of the parent directory.
The description field, also mandatory (up to 1024 characters), carries the primary burden of skill activation. AI agents use this description to semantically match the user’s intent. If the description is too abstract, the skill will not be triggered; if it is overly broad, the skill will activate erroneously, cluttering the context window. Industry standards recommend writing the description in the imperative mood, focusing on the task the user wants to solve rather than how the skill is technically implemented.
In addition to mandatory fields, YAML-block supports several optional parameters. The license field specifies the usage license; the compatibility field (up to 500 characters) defines specific environment requirements (e.g., the presence of specific Python versions or access to private networks); the metadata field allows storing arbitrary key-value pairs (versions, author names); and the experimental allowed-tools field provides a way to restrict the list of tools the skill is authorized to invoke.
The second part of the file contains instructions in free-form Markdown. Effective skills are typically structured around defining the agent’s persona, describing expected output formats, providing step-by-step guides, and setting strict boundary rules (e.g., prohibiting the use of professional jargon).
The Mechanics of Progressive Disclosure
A key architectural challenge when working with large language models is the limitation and degradation of the context window. Placing hundreds of corporate instructions directly into the system prompt exponentially increases token costs, slows down inference speed, and raises the likelihood of hallucinations. To address this, the Agent Skills standard implements a “progressive disclosure” paradigm consisting of three stages.
In the first stage (Discovery), the agent scans the file system upon startup and loads only the name and description fields of each available skill into its base system prompt. This process requires an average of about 100 tokens per skill, allowing the agent to have an “awareness” of a vast array of competencies without compromising working memory.
In the second stage (Activation), when the user assigns a specific task, the agent matches it against the loaded descriptions. If a relevant skill is found, the agent dynamically loads the full content of the SKILL.md instruction body (which is recommended to be kept under 5000 tokens).
In the third stage (Execution), the agent, guided by the loaded instructions, can optionally use file system tools to read voluminous corporate standards from the references/ folder or execute local scripts from the scripts/ folder. This approach makes the skill’s total knowledge capacity virtually limitless while maintaining a minimal footprint in the agent’s active context window.
Cross-Platform Interoperability: Claude Code, Codex, and Antigravity
One of the most significant concerns when adopting agentic systems is avoiding vendor lock-in. An analysis of architectural specifications and software implementations confirms that skills developed for Claude Code are fully compatible and interchangeable with OpenAI Codex, Google Antigravity, and other systems supporting the Agent Skills standard.
Initially, the SKILL.md format was developed by Anthropic engineers for use within Claude Code. Recognizing the value of unification, Anthropic published the format as an open standard, leading to its widespread adoption across the AI development ecosystem. Currently, the specification is supported by more than 30 different products, including Cursor, GitHub Copilot, Block’s Goose, LM-Kit.NET, Mistral Vibe, and OpenClaw.
Despite fundamental compatibility at the specification level, each platform has its own nuances regarding loading mechanisms, path hierarchies, and security policy applications.
Requires the explicit –enable skills flag. Supports an administrative skill tier that cannot be overridden at the project level (for corporate policies). Unlike the deprecated AGENTS.md, skills do not clutter the context.
Google Antigravity
~/.gemini/config/skills/ or ~/.gemini/antigravity/skills/ (global), .agents/skills/ (local)
Converts skills into slash commands (e.g., /format-tests). Supports parallel execution via subagents and integration with the Antigravity 2.0 platform.
LM-Kit.NET
Relative paths integrated into the .csproj build
C# implementation. Uses a SkillRegistry for dynamic skill scoring (including semantic search via embeddings) and wraps skills in a SkillTool for invocation via LLM functions.
To facilitate migration between platforms, the ecosystem provides automated conversion tools. The claude-skills library (developed by Alireza Rezvani) includes specialized bash scripts, such as convert.sh and install.sh. These scripts allow developers to transform standard SKILL.md packages into formats required by specific tools with a single command: for instance, into .mdc rules for Cursor, CONVENTIONS.md files for Aider, or directory structures for Windsurf and OpenCode. Thus, a corporate knowledge base, written once in the Agent Skills format, becomes a cross-platform asset accessible in any modern IDE.
Skill Generators: Tools, Services, and Approaches
Manually creating an effective skill is an iterative process that requires meticulous prompt engineering, testing activation triggers, and adhering to strict YAML formatting rules. To lower the barrier to entry and accelerate development, a class of tools known as skill generators was created. They range from simple web interfaces to complex, context-aware CLI agents.
Below is an overview of the main tools for automating and generating skills:
1. Official Anthropic Utilities (Initialization Scripts)
For developers building CI/CD pipelines and preferring to work in the terminal, the official anthropics/skills repository provides a set of basic Python scripts.
The init_skill.py script: Automatically creates the boilerplate file structure (scripts/, references/, assets/ folders) and a baseline SKILL.md file with a correctly formatted YAML block. This eliminates the need to create directories and structure manually (mkdir -p).
The package_skill.py script: Performs strict validation. It checks for the presence of mandatory fields, character length limits, directory naming conventions, and the integrity of links to external files. Upon passing the audit, the utility archives the directory into a distributable .skill format.
2. WebSearchAPI.ai Claude Code Skills Generator
This tool is a web-based generator that automates the creation of SKILL.md files based on a natural language description of the user’s intent.
The service operates by orchestrating powerful language models (such as Spark 1 Pro and Spark 1 Mini) with Firecrawl search agents. The generator’s architecture eliminates the need to manually write markup. The user formulates requirements in natural language, and the system, relying on official Anthropic specifications, constructs the skill’s structure. If the generation requires knowledge of specific third-party APIs, an internal agent conducts a targeted web search, extracts only relevant documentation, structures it, and integrates the acquired knowledge into the final Markdown file. The result is a ready-to-use file that simply needs to be placed in the ~/.claude/skills/ directory.
A more fundamental approach to generation is offered by tools capable of analyzing the existing project context. Antigravity Skills Generator, developed by researcher Anilcancakir, acts as a specialized AI assistant launched in PLANNING MODE.
Instead of generating skills in a vacuum, this tool conducts a deep audit of the codebase, reads root configuration files (e.g., GEMINI.md), and identifies complex, multi-step procedures that require expert solutions. The generator can distinguish between global hard project rules and specific expertise that should be packaged as a separate skill (e.g., database performance auditing or framework specifics). SKILL.md files are only generated after the user approves the identified needs, making this tool ideal for large enterprise projects.
4. Generators as Part of the Code Ecosystem: Awesome Claude Code
The Awesome Claude Code plugin (developed by Roman Dykyi) deserves special attention as it transforms the Claude Code CLI into a powerful architectural environment for PHP developers. This system unites over 300 specialized components and introduces the concept of Generator Skills.
In this architecture, skills don’t just store information—they actively generate code and suggest refactoring to fix identified issues. The tool uses a task delegation pattern: a high-level coordinator (e.g., architecture-auditor) analyzes the project and delegates highly specialized tasks to subordinate subagents. Each agent has access only to the generator skills it needs. For example, a security reviewer uses OWASP tools, while a DDD auditor relies on domain-driven design skills. This demonstrates the transition of skills from passive encyclopedias to active, self-sufficient participants in the development process.
Ecosystem and Marketplaces of Ready-Made Skills
The evolution of the open standard has led to the formation of a massive ecosystem of public repositories, marketplaces, and curated lists, allowing developers to reuse industry best practices rather than generating skills from scratch.
One of the most comprehensive libraries is the alirezarezvani/claude-skills repository, which has garnered over 17,000 stars on GitHub. This project provides 345 fully ready-to-use skills covering not only programming but also domains like marketing, compliance, business operations, and C-level analytics. A standout feature of this library is the integration of 602 Python scripts designed to run exclusively using the language’s standard library (no pip install required). These scripts allow agents to perform deep analyses of process bottlenecks (BPMN), assess counterparties across risk vectors, or optimize pricing, acting as fully autonomous CLI tools.
Other notable resources include:
The anthropics/skills repository: The official library containing reference examples of skill implementations for creative content generation, web application testing, and complex manipulations with Microsoft Office formats (PDF, Word, Excel, PowerPoint).
The sickn33/antigravity-awesome-skills repository: A massive catalog containing over 1,340 skills, optimized for the Antigravity ecosystem but compatible with other agents.
Curated collections (shahshrey/awesome-claude-code-mastery, obviousworks/Claude-AI-skills-collection-2026): Indexes systematizing skills for scientific research (computational biology, Scanpy, RDKit tools), visual design, and infrastructure auditing.
Connecting such knowledge bases to a workflow is accomplished via marketplace systems. In Claude Code, executing the command /plugin marketplace add [repository_name] is sufficient to install entire packages of procedural knowledge (e.g., document-skills) directly from the developer’s terminal.
AI Skills vs. Model Context Protocol (MCP)
During the integration of agentic systems, architects often encounter confusion between two fundamental standards, both originally incubated by Anthropic: Agent Skills and the Model Context Protocol (MCP). Understanding the difference between them is critical, as they are not competing technologies but rather form two complementary layers in the modern “Agentic Stack.”
The main difference lies in their purpose. Skills (Agent Skills) form the agent’s procedural memory—its internal knowledge of how to perform tasks. MCP, on the other hand, provides a sensory interface, defining where and with what the agent can interact.
Architectural Showdown: Filesystem vs. Client-Server
The Model Context Protocol is an open protocol that standardizes secure methods for connecting AI models to external services, databases, and systems (such as Slack, GitHub, Notion, local file systems, and corporate APIs).
Architecturally, MCP implements a strict client-server model. The AI agent (MCP Host) connects to an independently running process (MCP Server) via a transport layer (stdio or HTTP), exchanging messages using the JSON-RPC protocol. This paradigm ensures a high level of isolation: the agent does not have direct access to the server’s source code or its memory; it merely requests the execution of specific tools or the retrieval of resources via strictly typed schemas. This model is ideal for integrations requiring complex authentication (e.g., OAuth 2.0), persistent connection management, and strict data access control.
Skills, as described earlier, rely on the file system. The agent has direct access to the skill’s directory, reads instructions in natural language, and executes local scripts within its own process.
The Synergy of Two Layers
The limitations of each standard individually are compensated for by their combined use. The MCP protocol gives the agent the ability to connect to a corporate PostgreSQL database, but it cannot teach the agent how to write efficient, secure, and optimized SQL queries that account for the organization’s specific business logic. This task is solved by skills.
Thus, in complex workflows (e.g., during security incident investigations), skills provide the investigation methodology and reporting standards, while MCP tools grant the agent the ability to pull logs from remote servers and publish the results to a corporate messenger.
Characteristic
Agent Skills
Model Context Protocol (MCP)
Functional Role
Internal expertise, logic, and methodologies.
External integration, tools, and data access.
Execution Architecture
Local files and scripts within the agent’s process.
Separate server process (stdio/HTTP).
Security Policy
High blast radius, no built-in RBAC.
High level of isolation, independent authentication.
The fundamental architecture of the Agent Skills specification, which prioritizes development speed and flexibility, introduces significant information security risks. Unlike MCP servers, skills execute within the same process as the AI agent itself, inheriting all the privileges of the developer’s host system.
The specification does not mandate process isolation mechanisms, network shielding, or secrets management. When an agent activates a skill containing executable code or complex setup scripts, that code gains uncontrolled access to the local file system, system environment variables, configuration files (which may store API keys, AWS tokens, and session data), and the network.
Attack Vectors and the ClawHavoc Campaign
Theoretical concerns were validated in the first half of 2026 during massive attacks on the OpenClaw ecosystem and its central skills marketplace, ClawHub. Research teams from Unit 42, Koi Security, and Bitdefender uncovered a coordinated malicious campaign dubbed ClawHavoc, resulting in the compromise of hundreds of skills.
Attackers employed a multi-faceted approach to attack the AI software supply chain:
Typosquatting and Disguise: Malicious skills were published under names visually indistinguishable from popular utilities (e.g., Google Workspace integrations, Polymarket bots, or updaters).
Rating Manipulation (ClawHub Vulnerability): Researchers from Silverfort demonstrated a critical vulnerability in the marketplace’s ranking algorithms. By bypassing rate-limiting and deduplication systems, attackers artificially inflated their modules’ download counts by tens of thousands. The marketplace’s algorithms pushed these skills to the top spots, tricking the AI agents themselves (which rely on popularity when autonomously selecting tools) into downloading and installing malicious code.
Fake Prerequisites Mechanism: Exploiting the LLM’s ability to interpret natural language, instructions within SKILL.md convinced the agent that mandatory “pre-configurations” were necessary. Following the instructions, the agent automatically extracted hidden code in the documentation (typically a Base64 encoded curl-pipe-bash dropper) and executed it in the system terminal.
Infostealer Delivery and Exfiltration: The primary payload in the ClawHavoc campaign was the AMOS (Atomic macOS stealer) malware. It harvested passwords from the keychain, cryptocurrency wallet data, SSH keys, and also extracted the AI agent’s own credentials (e.g., from ~/.clawdbot/.env config files), covertly transmitting them to attacker-controlled command and control servers (C2 infrastructure, such as 91.92.242.30). Some skills embedded reverse shells directly into the functional code, activating not during installation but during the developer’s regular workflow.
Mitigation Strategies and Auditing
In response to these threats, the industry has implemented multi-layered verification systems. Traditional antivirus integrations (e.g., VirusTotal on the ClawHub platform) demonstrated limited effectiveness, as malicious functionality is often hidden not in binary code but in natural language semantics or masked by “junk” data designed to exceed scanner file size limits.
A more effective approach has been the use of AI auditing. The SkillSpector system, developed by NVIDIA, utilizes semantic analysis to detect hidden instructions, excessive permissions, memory poisoning risks, and discrepancies between a skill’s declared function and its actual behavior. At the end-user level, protective plugins are actively being deployed (e.g., ClawNet by Silverfort), which intercept tool calls during the installation phase and force the local model to conduct a risk analysis of the downloaded SKILL.md before it is saved to disk.
Corporate security teams are advised to avoid automatically downloading skills from public marketplaces. Instead, they should employ strict manual code review procedures (especially for scripts requiring credentials), deploy agents in isolated containerized environments with restricted network access, and apply the principle of least privilege to environment variables.
Methodology for Designing Effective Skills
For teams creating skills internally or modifying generated code, adhering to strict architectural practices is crucial. The development process should begin not with writing instructions, but with a deep understanding of user intent.
The following algorithm for skill creation is recommended:
Gather Use Cases: Identify the exact phrasing users will employ when making a request. This forms the basis for a proper description (the description field).
Plan Resource Structure: Decouple the logic. Repetitive algorithmic actions should be moved to scripts (scripts/), while lengthy corporate guidelines belong in reference files (references/). This maximizes the benefits of the progressive disclosure mechanism.
Optimize the Description Field (The Trigger Triad): The description must be concise, use the imperative mood (“Use this skill when…”), and explicitly list the contexts in which the skill is relevant. An under-detailed description will result in the agent never calling the skill, while an overly broad one will lead to constant misfires.
Structure the Instruction Body: Ambiguity should be avoided in the Markdown section of the skill. It is necessary to provide clear sequences of actions, offer examples of baseline outputs, and explicitly state which external files the agent should consult if non-standard situations arise.
Synthesis
The evolution of AI-powered coding tools has led to the formation of complex agentic ecosystems where foundational models act merely as the computational core. The Agent Skills standard has radically transformed how these systems’ capabilities are extended, allowing developers to encapsulate procedural knowledge, corporate playbooks, and specialized methodologies into lightweight, portable formats.
The progressive disclosure architecture elegantly resolves the context window overflow problem, enabling AI agents to operate with virtually unlimited amounts of data without performance loss. The standard’s interoperability guarantees that expertise created today for Claude Code can be applied without fundamental changes in environments like OpenAI Codex, Google Antigravity, or LM-Kit.NET.
Automated skill generation tools, ranging from Firecrawl-powered web services to context-aware IDE utilities, significantly lower the barrier to entry into the ecosystem. In tandem with the Model Context Protocol (MCP), which provides a secure bridge to external data and services, skills form a full-scale agentic stack capable of autonomously solving complex architectural challenges.
Nevertheless, integrating executable code and natural language instructions directly into the agent’s process introduces new classes of vulnerabilities in the software supply chain. The experience of combating malicious campaigns demonstrates the need to move from traditional antivirus solutions to semantic analysis methods and strict computational environment isolation. Organizations that successfully adopt standardized AI skills while adhering to modern security requirements will gain an unprecedented advantage in automating software design and development processes.
FAQ
What are Agent Skills?
Agent Skills are a lightweight, open standard for packaging procedural knowledge, workflows, and tools into modular directories. They teach AI agents like Claude Code exactly how to perform specific tasks using a “progressive disclosure” architecture, allowing agents to access domain-specific expertise on-demand without clogging up their context window.
How do Agent Skills differ from the Model Context Protocol (MCP)?
While both extend an AI agent’s capabilities, they serve completely different purposes. Agent Skills provide internal expertise and methodology (the “how”), acting as a playbook that lives locally with the agent2. MCP, on the other hand, is a sensory interface that gives the agent connectivity to external tools and data (the “where” and “what”)3. For example, MCP connects the agent to a database, while a skill teaches the agent how to write safe and optimized SQL queries.
Can I use Claude Code skills on other platforms?
Yes. Because they are built on the Agent Skills open standard, skills created initially for Claude Code can be used seamlessly across a wide variety of AI coding tools. This includes OpenAI Codex, Google Antigravity, Cursor, and LM-Kit.NET, ensuring your custom workflows aren’t locked to a single vendor.
What makes a good skill description in the SKILL.md file?
The description field is critical because it acts as the primary trigger for the agent to load the skill. A good description should be written in the imperative mood (e.g., “Use this skill when…”), focus on what the user is trying to achieve rather than the skill’s technical implementation, and explicitly list the contexts where the skill is relevant. It must also remain concise, staying under the specification’s 1024-character limit.
Are there security risks associated with Agent Skills?
Yes. Because skills run in the same process as the AI agent itself, they inherit the privileges of the host system. If you install a malicious skill from a public marketplace, it could execute hidden code, access local environment variables, or exfiltrate sensitive credentials, as seen in the ClawHavoc campaigns. It is highly recommended to manually vet skills or use AI-based security auditing tools before installation.
Do I have to write skills entirely from scratch?
No, you can utilize skill generators to automate the tedious parts of the process. Tools range from simple web-based generators (like WebSearchAPI.ai) that create proper SKILL.md structures based on natural language descriptions, to deep context-aware CLI plugins (like Awesome Claude Code or the Antigravity Skills Generator) that analyze your project’s codebase to generate highly tailored skills and code components automatically.
