SKILL.md, the King of Shadow AI

What is SKILL.md? SKILL.md is the file at the heart of an agent skill, defined by the open Agent Skills standard: Markdown with YAML frontmatter that gives the skill a name and a description, then instructions the agent loads only when a task matches. Scripts, references and assets can sit alongside it.

Agent Skills are a brilliant idea

Let’s be clear from the outset: Agent Skills are an excellent idea.

Released by Anthropic in late 2025, the format is elegant: a self-contained folder with a SKILL.md file in Markdown, YAML frontmatter, and optionally a few scripts or reference documents. When an agent encounters a task, it discovers the relevant skills and loads only the instructions it needs, keeping context light and adaptable.

The progressive disclosure principle is particularly clever: only the bare minimum enters the context window, and only when it’s useful. It’s efficient, it’s modular, it’s readable by a human and by a machine. The promise is a strong one: capture business expertise in a durable form, rather than diluting it across throwaway prompts.

In short, as a technical format, SKILL.md is a success.

But here’s the thing: what makes it strong is also what makes it fragile. Not the format itself: the organizational architecture it’s being deployed into.

The real problem: a format without governance

To see why, look at where skills actually live in most deployments today:

• In a skills/ folder on a developer’s laptop
• In a personal GitHub repository, sometimes public
• In ~/.claude/skills/, shared across projects with no inventory
• In community marketplaces with no internal review
• In a shared Drive or Notion folder, copy-pasted between colleagues

In other words: every skill is created, modified, shared and executed entirely outside any enterprise framework.

Meanwhile, inside that same company:

• EQS Group’s 2026 Privacy Barometer shows that 80% of French organizations have no clear view of their AI risks.
• Netskope’s Cloud and Threat Report: 2026 finds that 47% of generative AI users still work through personal AI apps.
• The Oh, Behave! 2025-2026 report by the National Cybersecurity Alliance and CybSafe finds that 43% of workers share sensitive work information with AI tools without their employer’s knowledge.

Shadow AI was already a serious problem when it meant ChatGPT and Claude accessed through personal accounts. Agent Skills take it to another level: what leaves the company is no longer just data, it’s business expertise: encapsulated, versioned, shared, and completely invisible to IT.

Why SKILL.md makes Shadow AI worse

1. Tight coupling to the LLM or agent

A skill, as currently deployed, is welded to its execution engine. The SKILL.md format itself has been an open standard since December 2025, but each vendor stores, shares and runs skills its own way: a skill uploaded to Claude lives in Claude, one installed for Codex lives in Codex, a Copilot Studio skill lives inside the Microsoft ecosystem. Even within one vendor, custom skills do not sync across surfaces.

The practical consequence: to use a skill, you have to adopt (and usually pay for) the corresponding LLM. Every business team that discovers an interesting skill library brings a new vendor with it: a new pricing model, a new data processing agreement. IT finds out about the commitment after the fact.

This is the classic Shadow IT scenario, with a multiplier: a skill isn’t an isolated tool, it’s a block of business capability that creates operational dependency the moment it’s adopted.

2. No concept of organization

A skill has no idea which company it belongs to, which department, which function. It has no identified owner, no declared consumer, no org unit it reports into.

The result:

• No mapping is possible: there is no way to answer “how many skills are running in my company?”
• No pooling: three teams can build three near-identical skills for the same task.
• No lifecycle: who maintains a skill once its author leaves the company?
• No audit trail: you cannot produce an inventory of deployed AI systems, the starting point of any AI Act compliance work.

Article 4 of the EU AI Act, as amended by the 2026 AI omnibus, requires providers and deployers to take measures supporting the AI literacy of everyone who operates these tools on their behalf. That’s hard to deliver when you don’t even know which skills are in circulation.

3. No permissions, no ownership, no traceability

A SKILL.md file carries no notion of:

• Who is allowed to create it.
• Who is allowed to consume it.
• Who is accountable for its quality and compliance.
• Which uses must be logged.

It’s a sharing format, not a governance format. And that is precisely what makes it, paradoxically, the ideal format for Shadow AI: easy to create, easy to distribute, impossible to track at enterprise scale.

4. Duplication and drift

With no central catalog, business expertise dissolves into an endless set of diverging copies. The “client report generation” skill exists in seven versions, each with its own reading of the rules, its own hardcoded company data, its own bugs.

When the GDPR audit arrives, when the AI Act calls for documentation of the AI system behind an automated decision, when a customer exercises their right to erasure, nobody can answer.

This isn’t a bug, it’s a missing layer

Let’s be fair to Anthropic: SKILL.md never claimed to be a governance platform. It’s a format, and an excellent one, but only a format. The problem is that no organizational layer has been built on top of it, and the community treats that gap as if it weren’t there.

The parallel is instructive. Source code doesn’t govern itself: we had to invent Git, then GitHub, then pull request reviews, then CI/CD pipelines, then branch policies. Data doesn’t govern itself: we had to invent data catalogs, data contracts, data products. Skills need their orchestration layer too.

One approach: channel the initiative with a framework like skilder

That’s exactly the angle a framework like skilder takes. The point isn’t to replace the SKILL.md format, which remains excellent, but to add a layer of organization, ownership and coordination on top of it.

The core concept: the Role

A Role is a named, thematic collection of skills that maps to an actual function or persona in the company. Instead of letting skills float around loose, you group them by business use:

• A “Pre-Sales” Role gathers the skills for handling objections, drawing on competitive intelligence, and guiding a prospect through the sales cycle.
• A “Legal Assistant” Role gathers the skills for contract analysis, regulatory monitoring, and drafting amendments.
• A “DevOps” Role gathers the skills for deployment, monitoring, and incident response.

When an employee, or an agent, takes on the “Pre-Sales” Role, they get the full, coherent set of capabilities approved for that function in one move. No more, no less.

Why this changes everything

This deceptively simple mechanism resolves several structural problems of Shadow AI:

1. It channels initiative instead of banning it. A salesperson who cobbled together their own skill can propose it for inclusion in the “Sales” Role. Individual initiative becomes a company asset instead of staying in the shadows.
2. It makes mapping trivial. “Which skills are running in my company?” becomes simply “which Roles do we have, and what’s inside them?”. The catalog is centralized, versioned, audited.
3. It introduces explicit ownership. Every skill has an owner and declared consumers. Maintenance, quality and compliance have a name and a face attached.
4. It decouples expertise from the execution engine. With an MCP-compatible approach, where skills compose MCP tools instead of replacing them, the same skill can be consumed by Claude, by Copilot, or by an in-house agent, with no rewrite. No more implicit vendor lock-in.
5. It makes context selection intelligent. Instead of loading the entire library into the context window, the agent loads only the skills in the active Role. Fewer tokens, fewer hallucinations, better performance.
6. It offers a credible alternative to Shadow AI. The core problem with Shadow AI isn’t that employees have bad intentions. It’s that they need to be productive and the official tools arrive too late. Giving teams a platform where they can build, share and consume approved skills inside the company’s boundary means offering the fluidity of the shadow with the guarantees of the sanctioned.

The conceptual architecture

The idea fits in a few lines:

Workspace (enterprise boundary)
└── Roles (business functions / personas)
    └── Skills (units of capability, SKILL.md compatible)
        ├── Instructions
        ├── MCP tools (LLM-agnostic)
        ├── References (markdown documents)
        └── Scripts (Python, sandboxed execution)

The SKILL.md format is preserved. A standard Anthropic skill can be imported as-is. But it now belongs to a workspace, is organized into Roles, exposed through an agent-agnostic protocol (MCP), traced, versioned, and subject to explicit permissions.

What this means for CIOs and AI leads

If you own AI governance in your organization today, here is the concrete question to ask: could you, this morning, list every SKILL.md file circulating in your company?

If the answer is no (and when 80% of organizations lack a clear view of their AI risks, it usually is), then publishing a policy or banning ChatGPT is no longer enough. The missing layer is structural:

1. Map what already exists. The skills already sitting in Git repositories, in ~/.claude/, in marketplaces. This is the AI equivalent of the GDPR record of processing activities.
2. Centralize creation. One place where a skill is declared, versioned and published, with an identified owner and consumer.
3. Structure by Role, not by technology. Think Roles before you think models. A salesperson doesn’t need to know whether they’re using Claude or GPT. They need the “Sales” Role.
4. Decouple from the LLM. Pick an abstraction layer (MCP is today’s de facto standard) that lets you swap models without rewriting your skills.
5. Make internal skill creation official. Shadow AI thrives when the official channel is slower than the unofficial one. If getting a skill approved takes 48 hours and comes with an identified owner, nobody will bother building one on the side.

To see where your organization stands on these practices, take the free AI check-up: ten yes/no questions, two minutes, no form.

Conclusion

SKILL.md isn’t the problem. It may well be one of the best formats for encapsulating AI expertise to have emerged in the last two years.

But a format is not a platform. And as long as the ecosystem keeps treating skills the way we treated shell scripts in 2005 (passed around by hand, no owner, no catalog, no lifecycle), SKILL.md will remain, despite itself, the king of Shadow AI: the most convenient, most shareable and most invisible format enterprises have ever let into their systems.

The good news is that the fix isn’t to replace the format. It’s to add the organizational layer it’s missing. Roles to structure how the business actually works. A workspace to draw the enterprise boundary. MCP compatibility to avoid vendor lock-in. A catalog to make visible what’s already circulating.

Shadow AI isn’t a signal that AI should be banned. It’s a signal that it finally needs a framework where it can thrive without hiding.

---

Want to map the skills already circulating in your organization, or structure their adoption around clear business roles? That’s exactly the problem skilder solves.

Frequently asked questions

What is SKILL.md? +

SKILL.md is the file that defines an agent skill under the open Agent Skills standard. It opens with YAML frontmatter holding a required name (lowercase, up to 64 characters) and a description of what the skill does and when to use it, followed by Markdown instructions. Optional folders such as scripts, references and assets sit alongside it. Agents read the name and description at startup and load the rest only when a task matches.

Does SKILL.md only work with Claude? +

No. Anthropic introduced the format in October 2025 and published it as an open standard on 18 December 2025, and clients such as OpenAI Codex, GitHub Copilot, VS Code, Cursor and Gemini CLI now read it. The file is portable; where each product stores and shares it is not. Claude's own documentation notes that custom skills do not sync across its surfaces: a skill uploaded to claude.ai, to the API and to Claude Code means three separate copies.

Why are SKILL.md files a shadow AI risk? +

Because a skill is easy to write, copy and install, and carries no owner, permission or audit trail of its own. Community directories such as the open skills.sh ecosystem put a skill one install command away, and Anthropic's documentation advises using skills only from trusted sources, since a malicious skill can direct the agent to run code or leak data. Without an inventory, nobody knows which skills run on which data, or who answers for them.