How PayPal is governing agent skills at enterprise scale

Teams keep the repositories and workflows they already own. A shared marketplace adds discovery, security validation, human review, versioning, and governed distribution.

By Faiz Mohammed, with Simon Xu, Shangyuan Jia, Froyo Dai, Digvijay Singh, Amy Wang, and Srinivasan Manoharan

Agent skills turn the best-known way to do a task into a reusable package that compatible AI agents can follow. At PayPal, the challenge was not only helping teams create skills. It was creating a trusted path for thousands of employees to discover and reuse them without taking ownership away from the teams that maintain the underlying expertise.

Our design choice: decentralize authoring. Centralize trust, governance, and distribution.

What is an agent skill?

An agent skill is a folder that teaches an AI agent how to complete a specific task consistently. Its SKILL.md file describes when the skill should be used and the workflow to follow. The package can also include examples, templates, reference material, guardrails, and tested scripts.

The format follows the Agent Skills open specification (agentskills.io/specification). Instead of re-explaining a process in every prompt, a team encodes its best-known approach once and maintains it like any other shared engineering asset.

A skill is a portable, versioned folder that packages instructions, context, and optional executable assets into one reusable unit:

Component	Purpose
SKILL.md	Metadata, activation guidance, and task instructions.
References	Detailed standards and domain context loaded when needed.
Scripts and assets	Tested automation, templates, and reusable resources.

Why enterprise reuse needs governance

Skills can capture brand standards, recurring business processes, codebase conventions, onboarding knowledge, and repeatable automation. They are also lightweight by design: an agent first sees a short name and description, then loads detailed instructions and supporting files only when a task calls for them.

That leverage comes with a new trust boundary. A skill is not just documentation. It can contain instructions and executable code, and an agent may run it with the user's permissions. An unreviewed skill can therefore become a software supply chain risk.

• Up to 95%: LangChain reported a substantial task-success improvement after adding framework-specific skills to its coding-agent evaluation.
• 36.8%: In Snyk's 2026 ToxicSkills study of 3,984 public skills, more than a third had at least one security issue and 76 were confirmed malicious.

Keep your repository. Add a governed distribution layer.

A central marketplace should not force every team into a central authoring repository. Internal teams already have established GitHub repositories, review practices, ownership models, and release workflows. We designed the PayPal Skills Registry to work with those systems rather than replace them.

A team can connect a selected repository by installing a PayPal-managed GitHub App with read-only access to repository contents. On the first connection, the registry discovers the skills in that repository and creates onboarding submissions for them. After that, GitHub webhook notifications tell the registry when an existing skill changes or a new skill is added.

Those notifications do not bypass governance. They start it. The registry pulls the relevant package, creates a new submission or version, and sends it through the same validation and human-review path as every other contribution.

Repository ownership stays with the team

The marketplace observes selected repositories through narrowly scoped access and governs what becomes broadly reusable.

Team source of truth	Narrow integration	Registry intake
Team-owned GitHub repository. Engineers contribute, review, and maintain skills alongside their normal work.	Read-only GitHub App. The team selects the repository; the app reads skill content but does not write to the team's code.	Initial discovery plus continuous updates. The registry creates governed submissions instead of directly publishing repository content.

• First onboarding: discover all valid skill folders in the selected repository and start onboarding each package.
• Ongoing maintenance: webhook notifications identify new or changed skills and trigger a fresh registry submission.

PayPal governed trust boundary

Stage	What happens
1. Create submission	Record source, owner, metadata, and proposed version.
2. Validate package	Run required security, policy, quality, and structure checks.
3. Human review	An authorized administrator reviews intent, results, and ownership.
4. Publish	Only an approved version becomes discoverable in the internal marketplace.

The repository remains the team's authoring system. The Skills Registry becomes the enterprise system of trust, discovery, versioning, and distribution. Every new or updated skill re-enters the governed path before it is made available for broad internal use.

Security is a pipeline, not a final checkpoint

We developed the validation pipeline in partnership with PayPal Product Security. Their contribution is not a one-time sign-off. Security controls continue to evolve as the skill format, threat landscape, and enterprise use cases evolve.

Whether a skill arrives through a repository connection or a package upload, required checks fail closed. A green pipeline is necessary, but it is not sufficient. Every submission still requires an authorized human reviewer before the skill can be published.

The current blocking baseline validates package structure, checks for embedded personal or sensitive data, identifies harmful instructions, and reviews the package for prompt injection and other LLM-abuse patterns. Duplicate detection runs as an advisory signal so reviewers can reduce catalog fragmentation without turning similarity alone into a publication failure.

Layered validation pipeline

Control	Scope
1. Package structure	Required metadata, naming, SKILL.md, and package integrity.
2. Sensitive data	Personal or sensitive information embedded anywhere in the skill package.
3. Harmful instructions	Dangerous commands, destructive intent, and credential-abuse language.
4. Prompt injection / LLM abuse	Policy bypass, hidden instructions, exfiltration, and overbroad access.
5. Duplication (advisory)	Overlap detection to reduce fragmented or redundant catalog entries.

Automation answers	Human review answers
Did the required checks pass? Required failures block the submission; advisory findings remain visible to reviewers.	Should this be trusted and published? An administrator verifies ownership, intent, scope, and the complete result.

Checks cover the complete skill package, not only SKILL.md, and run again for every proposed version.

The roadmap phases in secret scanning, static analysis, dependency and license scanning, software bills of materials, behavioral evaluations, and red-team evaluations through controlled rollout.

One marketplace, many team-owned sources

Once approved, a skill becomes discoverable in PayPal's internal marketplace with its owner, version, visibility, and validation status attached. Employees can download approved packages or install them through supported command-line and AI-tool workflows.

This creates a useful separation of responsibilities. Teams remain accountable for the expertise and source material. The registry is accountable for intake, validation, approval state, version history, access controls, and broad distribution.

• Meet teams where they work. Keep GitHub as the authoring source instead of requiring manual downloads, uploads, or repository migration.
• Revalidate every change. A trusted version stays trusted because updates re-enter the same pipeline rather than silently replacing approved content.
• Publish deliberately. Automation provides scale, while human approval preserves accountability for what the enterprise distributes.

From governed skills to Agent Plugins

The newly published Agent Plugins 1.0 working draft (agent-plugins.org/specification) defines a vendor-neutral package format for two portable component types: Agent Skills and MCP servers. That model aligns closely with the distribution layer we are building at PayPal.

An Agent Plugin can package a curated collection of approved workflows, with each workflow represented as a skill, together with the approved MCP servers needed to connect those workflows to governed data and actions. The result is one installable unit that gives an AI tool both the guidance for how work should be done and the connections needed to do it.

We plan to support plugins tailored to business functions such as Sales, Marketing, HR, and IT & Tech, as well as personas such as Developer and Data Analyst. Authorized plugin owners will be able to select approved skills and approved MCP connections, then create a package for the needs of their organization or role.

Approved agent skills and approved MCP servers are packaged as an Agent Plugin, validated and approved, then distributed to Claude Desktop, Codex, and other AI tools.

The portable plugin core is assembled once, then published through the delivery path supported by each AI tool. Enterprise validation and human approval remain in front of distribution.

Conclusion

Enterprise adoption will not scale on prompts alone. Skills package reusable expertise, a governed marketplace establishes trust, and Agent Plugins turn approved workflows and connections into tailored distribution units.

For us, the central lesson is simple: governance does not have to mean centralizing authorship. By integrating with team-owned repositories through read-only access and webhook-driven updates, we can preserve team autonomy while creating a consistent enterprise path for security review, discovery, reuse, and plugin-based distribution.

Further reading

• Agent Skills overview and open specification: agentskills.io/home, agentskills.io/specification
• Agent Plugins overview and version 1.0 working draft: agent-plugins.org, agent-plugins.org/specification
• LangChain Skills: langchain.com/blog/langchain-skills
• Snyk Labs, ToxicSkills: snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/