luismori.

Agentic Development

AI Agents Agent Skills Codex Claude Code Platform Engineering Developer Tools

How to Build a Company Skill Registry for AI Agents

A practical guide to publishing, reviewing, and sharing SKILL.md agent skills inside a company, inspired by how public directories like skills.sh work.

29 min read

Agent skills are starting to look less like prompt snippets and more like a real distribution layer for AI work.

That is good news, but it also creates a new company problem: once every team writes its own SKILL.md files, where do they live, who reviews them, how do people discover them, and how do you prevent a helpful workflow from becoming an invisible supply-chain risk?

Public directories like skills.sh give us a useful pattern. They index skills from GitHub, expose install commands, rank popularity, and make skills discoverable across agents. A company registry should borrow the same shape, but add governance: ownership, versioning, approval, access control, telemetry, and security review.

This article is a practical design for that collaborative space.

TL;DR

  • A skill is usually a folder containing a required SKILL.md file, plus optional scripts/, references/, and assets/.
  • The name and description fields are not decoration. They are routing metadata that help an agent decide when to load the skill.
  • Public registries such as skills.sh work mostly as discovery and installation layers over GitHub-hosted skills.
  • Sharing a public skill can be as simple as publishing a repo that contains valid SKILL.md folders and giving people an install command.
  • Sharing private skills should be treated more like publishing internal packages than sharing prompts in a document.
  • A company registry should support review, ownership, versions, compatibility targets, changelogs, installation policies, and rollback.
  • A private skills.sh-style app needs two paths: a web app for discovery/governance and a CLI for installing skills into local projects or agent folders.
  • For private repositories, use a GitHub App installation token model instead of asking developers for personal access tokens.
  • Installing a skill can mean either downloading it locally for one developer or opening a pull request that vendors it into a repository.
  • Updating skills should be lockfile-driven: record the skill version or commit that was installed, compare it with the registry, then open an update PR.
  • Contributing skills should be a normal PR workflow into the registry repository, with validation, owners, and security review.
  • The biggest risks are stale instructions, vague trigger descriptions, unsafe scripts, hidden secrets, prompt injection, and skills that only work in the original author’s local environment.
  • Start with a private Git repository and an index file. Add API, search, telemetry, and approval workflows only after teams are actually reusing skills.

What You Will Learn Here

By the end, you should be able to:

  • explain how the SKILL.md format works
  • understand the rough model behind public directories like skills.sh
  • publish a skill publicly from a GitHub repository
  • design a private company registry for agent skills
  • design the app flows for installing, updating, and contributing private skills
  • understand where GitHub App authentication fits
  • define a review workflow for skills before installation
  • create a simple registry manifest your team can maintain in Git
  • spot the governance gaps before a skill ecosystem grows too fast

The Article Structure I Inferred

Your research prompt points to three connected questions:

  1. How do public skill directories work?
  2. How do you share skills publicly or privately?
  3. How would a company build a collaborative skill space without making a mess?

So the article follows this path:

SKILL.md format
      |
      v
Public discovery model: skills.sh and similar directories
      |
      v
Public publishing: GitHub repo + install command
      |
      v
Private sharing: internal repo or registry
      |
      v
Company operating model: review, ownership, security, telemetry

The expected audience is engineers, PMs, developer-experience teams, platform teams, and AI enablement leads who need a practical shared model, not just another “what is a prompt?” explainer.

What Is A Skill?

In the current agent ecosystem, a skill is a small package of procedural knowledge.

The minimum useful version looks like this:

my-skill/
|-- SKILL.md
|-- references/     optional docs loaded only when needed
|-- scripts/        optional executable helpers
`-- assets/         optional templates, examples, or files

The SKILL.md file usually has two parts:

---
name: api-contract-review
description: Review an API change for backward compatibility, schema drift, error semantics, pagination, auth, and rollout risk. Use when asked to review an API design, OpenAPI diff, or service contract.
---

# API Contract Review

Review the proposed API change in this order:

1. Identify added, changed, and removed fields.
2. Check whether old clients can keep working.
3. Compare error codes and auth requirements.
4. Inspect examples and OpenAPI files if present.
5. Return risks, required tests, and rollout notes.

If the repository has OpenAPI specs, inspect them before asking the user.

That description is especially important. Anthropic’s public explanation of Agent Skills describes a progressive disclosure model: agents can start with compact metadata, then load the full skill only when the task appears relevant. GitHub’s Copilot skill docs also make the same basic shape explicit: SKILL.md uses YAML frontmatter with required name and description, followed by Markdown instructions and optional supporting files.

In plain English: the description is the skill’s front door.

If it is too vague, the agent may never use it. If it is too broad, the agent may use it at the wrong time.

How Public Skill Directories Work

The public ecosystem is still young, but the pattern is becoming clear.

skills.sh describes skills as reusable capabilities for AI agents and provides an npx skills add owner/repo style installation flow. Its docs also explain that the leaderboard is based on anonymous telemetry from the CLI and that users should still review skills before installing them.

SkillsGate describes its public discovery layer as powered by skills.sh, calling it an open index of skills from GitHub. OpenAI’s public openai/skills repository, meanwhile, shows how Codex skills can be installed from curated or experimental folders using $skill-installer, including direct GitHub directory URLs.

So the public model looks roughly like this:

Author publishes skill repo on GitHub
        |
        v
Directory indexes SKILL.md files and repo metadata
        |
        v
Human or agent searches the directory
        |
        v
Installer fetches selected skill from source repo
        |
        v
Skill lands in the target agent's local skills folder

This is closer to a package-discovery layer than a traditional app store. The registry may show search, rankings, install counts, badges, and metadata, but the source of truth is often still a Git repository.

That architecture has a nice property: publishing is easy. If your repo is public and structured correctly, a directory can index it.

It also has a dangerous property: installing is easy.

A skill can contain instructions that influence agent behavior. It can also include scripts. That means teams should review registry-sourced skills with the same seriousness they bring to third-party dependencies.

Public Sharing: The Simple Path

If you want to share a public skill, start with a boring GitHub repo. Boring is excellent here.

agent-skills/
|-- README.md
|-- skills/
|   |-- api-contract-review/
|   |   `-- SKILL.md
|   |-- incident-brief/
|   |   |-- SKILL.md
|   |   `-- references/
|   |       `-- severity-model.md
|   `-- sprint-risk-review/
|       `-- SKILL.md
`-- LICENSE

Your README should answer:

  • What skills are included?
  • Which agents have you tested with?
  • How do people install one skill?
  • What permissions or tools does each skill need?
  • What license applies?
  • How should people report issues?

Example install commands:

# Install from a repo with the public skills CLI
npx skills add your-org/agent-skills --skill api-contract-review

# Install a Codex skill from a GitHub folder
$skill-installer install https://github.com/your-org/agent-skills/tree/main/skills/api-contract-review

For public skills, the skill itself is also marketing. Make it easy to inspect. Keep instructions readable. Put dangerous assumptions in the open. Do not hide critical behavior in a script with a cute name.

Private Sharing: The Company Version

Inside a company, the goal changes.

You are not just trying to make a skill discoverable. You are trying to make it trustworthy, reusable, and maintainable across teams.

The simplest private registry is just a private Git repository:

company-agent-skills/
|-- registry.yaml
|-- skills/
|   |-- frontend-accessibility-review/
|   |   |-- SKILL.md
|   |   `-- references/
|   |       `-- design-system-rules.md
|   |-- billing-migration-plan/
|   |   |-- SKILL.md
|   |   `-- references/
|   |       `-- billing-risk-checklist.md
|   `-- incident-postmortem/
|       |-- SKILL.md
|       `-- assets/
|           `-- postmortem-template.md
`-- scripts/
    `-- validate-skills.ts

Then registry.yaml becomes the first shared catalog:

skills:
  - name: frontend-accessibility-review
    path: skills/frontend-accessibility-review
    owner: design-platform
    version: 1.4.0
    status: approved
    visibility: company
    agents:
      - codex
      - claude-code
      - github-copilot
    permissions:
      network: false
      shell: false
      writes_files: false
    tags:
      - frontend
      - accessibility
      - design-system

  - name: billing-migration-plan
    path: skills/billing-migration-plan
    owner: payments-platform
    version: 0.9.0
    status: pilot
    visibility: payments-org
    agents:
      - codex
      - claude-code
    permissions:
      network: false
      shell: false
      writes_files: true
    tags:
      - billing
      - migration
      - risk-review

That file is not fancy. That is the point. It gives PMs, engineers, security reviewers, and enablement leads one place to discuss what exists.

A Practical Company Registry Architecture

You can build the registry in layers.

Layer 1: Git source of truth
  skills/, registry.yaml, CODEOWNERS, PR review

Layer 2: Validation
  frontmatter checks, broken link checks, dangerous pattern checks

Layer 3: Discovery
  generated docs site, search index, tags, owners, examples

Layer 4: Installation
  CLI command, internal package, symlink/copy into agent folders

Layer 5: Governance
  approvals, versions, changelog, deprecation, telemetry, rollback

You do not need all five layers on day one.

Most companies should start with layers 1 and 2. Once a few teams are actually using shared skills, build discovery. Once discovery works, add installation automation. Governance becomes much easier when the registry already has owners, versions, and status fields.

Building The Private Skills App

Now let’s make the app concrete.

Think of the private registry as an internal version of skills.sh, but with company trust boundaries:

                 +---------------------------+
                 | Private Skills Web App    |
                 | search, approve, install  |
                 +-------------+-------------+
                               |
                               v
+----------------+     +-------+--------+     +-------------------+
| GitHub OAuth   | --> | Registry API   | --> | GitHub App        |
| user identity  |     | policy + index |     | repo operations   |
+----------------+     +-------+--------+     +---------+---------+
                               |                        |
                               v                        v
                       +-------+--------+      +--------+----------+
                       | Registry DB    |      | Registry Repo     |
                       | metadata/cache |      | skills/ + PRs     |
                       +----------------+      +-------------------+
                               |
                               v
                       +-------+--------+
                       | Skills CLI     |
                       | install/update |
                       +----------------+

The important split is this:

  • The web app helps people discover, review, approve, and request installs.
  • The registry repository remains the source of truth for skill content.
  • The database stores searchable metadata, install events, ownership, approvals, and cached versions.
  • The GitHub App performs repository operations without needing every developer to create a personal token.
  • The CLI installs skills into local folders because the web app cannot safely write to a developer’s machine.

You can build this with a very ordinary stack:

Frontend:        Next.js, Astro, Remix, or your internal platform
Backend:         Node.js, Go, Python, or Rails
Database:        Postgres
Search:          Postgres full-text first, OpenSearch later if needed
Queue:           SQS, Cloud Tasks, Sidekiq, or BullMQ
Source control:  GitHub private repo
Auth:            GitHub OAuth or company SSO
Repo access:     GitHub App installation tokens
CLI:             Node.js package, Go binary, or Python package

Do not start with a marketplace. Start with a useful internal catalog that can safely install one approved skill.

The Core Product Surfaces

The private app needs four primary screens.

Browse
  search, filter, compare, read SKILL.md

Skill Detail
  install commands, supported agents, owner, version, permissions

Contribute
  create or edit skill, validate, open PR

Admin
  approvals, repo installations, owners, policies, audit log

A skill detail page should show enough information for a developer or PM to decide whether the skill is safe and useful:

api-contract-review
Owner: platform-api
Status: approved
Version: 1.4.2
Source: github.com/acme/company-agent-skills/skills/api-contract-review
Supported agents: codex, claude-code, github-copilot
Permissions: no shell, no network, no file writes
Last reviewed: 2026-06-09

Install locally:
  skillhub install api-contract-review --agent codex

Install into repo:
  skillhub repo install acme/payments-api api-contract-review --path .agents/skills

Update:
  skillhub update api-contract-review

That page should also render the actual SKILL.md, not just marketing metadata. Skills are only trustworthy if people can inspect them.

GitHub App Authentication Model

For a company app, avoid asking users to paste personal access tokens into your registry.

Use two identities instead:

GitHub OAuth user token
  Who is this person?
  Which org/team/repo should they be allowed to see?

GitHub App installation token
  What repositories can the app read or write?
  Which installation granted access?

The GitHub App gets installed on the company organization or selected repositories. GitHub’s REST docs show installation objects containing repository selection, permissions, and an access_tokens_url. GitHub App installation access tokens are supported by repository contents and pull request endpoints, but the token needs the right permissions.

For a private skill registry, the practical permissions are:

Repository metadata: read
Repository contents: read
Repository contents: write       only if the app opens install/update PRs
Pull requests: read
Pull requests: write             only if the app opens contribution/install PRs

Use the minimum set that supports your chosen flow.

If the app only lets developers download skills locally, it may only need read access to the registry repository. If the app opens pull requests to install skills into product repos, it needs write access to contents and pull requests on those target repos.

Store this:

installation_id
account/org id
selected repositories
granted permissions

Do not store long-lived installation access tokens. Mint them when needed, use them, and let them expire. GitHub installation tokens are short lived, which is exactly what you want for this class of app.

Repository Access Rules

The app needs a clear answer to a deceptively simple question:

Who can install which skill into which repo?

Use a three-part rule:

User identity
  The person is a member of the company org or allowed team.

Skill visibility
  The skill is visible to the user's org, team, or repo.

Target repo permission
  The GitHub App is installed on the target repo and the user is allowed
  to request changes for that repo.

That gives you predictable behavior:

Can read registry repo?       yes
Can see this skill?           yes
Can write target repo?        no
Result: show install locally, but create repo PR is disabled

Can read registry repo?       yes
Can see this skill?           yes
Can write target repo?        yes
Result: allow repo install PR

Do not make “can open the app” equal “can install into any repo.” That shortcut feels convenient until someone installs an experimental database migration skill into a production service.

Registry Data Model

Keep skill content in Git. Keep searchable and operational data in Postgres.

create table skills (
  id uuid primary key,
  slug text unique not null,
  name text not null,
  description text not null,
  owner_team text not null,
  status text not null,
  visibility text not null,
  source_repo text not null,
  source_path text not null,
  current_version text not null,
  current_commit_sha text not null,
  created_at timestamptz not null,
  updated_at timestamptz not null
);

create table skill_versions (
  id uuid primary key,
  skill_id uuid not null references skills(id),
  version text not null,
  commit_sha text not null,
  content_sha256 text not null,
  changelog text,
  validation_status text not null,
  created_at timestamptz not null
);

create table skill_permissions (
  skill_id uuid not null references skills(id),
  permission text not null,
  value text not null,
  primary key (skill_id, permission)
);

create table installations (
  id uuid primary key,
  skill_id uuid not null references skills(id),
  version text not null,
  target_type text not null,
  target_repo text,
  target_agent text not null,
  target_path text not null,
  installed_by text not null,
  installed_at timestamptz not null
);

create table contribution_requests (
  id uuid primary key,
  skill_id uuid references skills(id),
  title text not null,
  author text not null,
  source_branch text not null,
  pull_request_url text,
  status text not null,
  created_at timestamptz not null
);

The content_sha256 matters. It lets you answer:

  • Which exact skill content was installed?
  • Did a local copy drift from the approved registry version?
  • Can we roll back to a known-good version?
  • Did someone change the skill without bumping the version?

Registry API Design

Keep the API small at first.

GET  /api/skills
  Search approved skills visible to the current user.

GET  /api/skills/:slug
  Return metadata, versions, rendered README/SKILL.md, and install options.

GET  /api/skills/:slug/download?version=1.4.2
  Return a tarball or zip of the skill folder.

POST /api/skills/:slug/install-local-token
  Create a short-lived download token for the CLI.

POST /api/repos/:owner/:repo/install
  Open a PR that vendors a skill into the target repo.

POST /api/repos/:owner/:repo/update
  Open a PR that updates installed skills based on the lockfile.

POST /api/contributions
  Create a branch and PR for a new or edited skill.

POST /api/webhooks/github
  Receive push, pull_request, installation, and installation_repositories events.

The local install endpoint should not return private GitHub tokens to the browser. Give the CLI a short-lived registry token, then let the backend fetch from GitHub and stream the bundle.

Install Flow 1: Local Developer Install

Local install means: “Put this skill on my machine or in this checkout.”

Developer runs CLI
        |
        v
CLI opens browser login or uses device code
        |
        v
Registry checks user, org, skill visibility
        |
        v
Registry fetches skill folder from private GitHub repo
        |
        v
CLI validates SKILL.md and writes target folder
        |
        v
CLI records lockfile entry

Example:

skillhub login
skillhub install api-contract-review --agent codex --scope project

Result:

.agents/
`-- skills/
    `-- api-contract-review/
        `-- SKILL.md

.skillhub.lock.json

Lockfile:

{
  "skills": {
    "api-contract-review": {
      "version": "1.4.2",
      "source": "github.com/acme/company-agent-skills",
      "path": "skills/api-contract-review",
      "commit": "4c1b2f7",
      "contentSha256": "7a4f..."
    }
  }
}

The lockfile is the difference between “I copied a prompt once” and “this repo intentionally uses version 1.4.2 of a reviewed skill.”

Install Flow 2: Repo Install By Pull Request

Repo install means: “Make this skill part of the repository so everyone gets it.”

User clicks Install into repo
        |
        v
App checks user + target repo permissions
        |
        v
App creates branch in target repo
        |
        v
App copies skill folder into .agents/skills/<skill>
        |
        v
App writes or updates .skillhub.lock.json
        |
        v
App opens pull request
        |
        v
Repo owners review and merge

The generated PR should be boring and auditable:

Title: Install api-contract-review skill

Files:
  .agents/skills/api-contract-review/SKILL.md
  .skillhub.lock.json

PR body:
  Skill: api-contract-review
  Version: 1.4.2
  Source commit: 4c1b2f7
  Permissions: no shell, no network, no file writes
  Registry page: https://skills.acme.dev/skills/api-contract-review

Use repo PRs for team-shared skills. Use local install for personal skills or experiments.

Update Flow

Updating skills is where many internal registries get sloppy.

Do not overwrite files silently. Compare the lockfile with the registry, then make the update visible:

Scheduled job or user request
        |
        v
Read .skillhub.lock.json from target repo
        |
        v
Compare installed versions with approved registry versions
        |
        v
Generate diff and changelog
        |
        v
Open update PR
        |
        v
Run skill validation in target repo

Example CLI:

skillhub outdated
skillhub update api-contract-review
skillhub repo update acme/payments-api --open-pr

Example update PR:

Title: Update api-contract-review skill to 1.5.0

Changes:
  - Narrows trigger description to OpenAPI and REST API reviews
  - Adds pagination compatibility checklist
  - Removes stale reference to legacy gateway

Validation:
  - SKILL.md frontmatter valid
  - No dangerous patterns detected
  - Lockfile content hash updated

This matters because skills are operational instructions. A skill update can change how agents review code, write migration plans, or touch production systems. Treat that as a real change.

Contribution Flow

Contributing a skill should feel like contributing code.

Contributor opens app
        |
        v
Chooses "New skill" or "Improve skill"
        |
        v
App provides template and validation feedback
        |
        v
Contributor submits
        |
        v
App creates branch in registry repo
        |
        v
App opens PR with generated checklist
        |
        v
Owners and security reviewers approve
        |
        v
Merge updates registry index

A new skill template should ask for:

Name
Trigger description
Owner team
Supported agents
Expected inputs
Expected outputs
Required tools
Required permissions
Example good output
Known failure modes
References

The generated SKILL.md should start conservative:

---
name: release-risk-review
description: Review a planned software release for rollout, customer impact, dependencies, observability, rollback, and communication risk. Use when asked to assess release readiness or create a release risk summary.
---

# Release Risk Review

Start by identifying the release scope, affected users, dependencies,
data migrations, operational risks, and rollback plan.

Do not approve the release. Produce a risk summary and unresolved questions.

The PR checklist should be part of the workflow:

## Skill Review

- [ ] Description clearly says when to use the skill
- [ ] Instructions are portable across repositories
- [ ] No secrets, tokens, or internal credentials
- [ ] Scripts are necessary and reviewed
- [ ] Permissions are declared
- [ ] Example output included
- [ ] Owner team assigned
- [ ] Rollback or deprecation plan documented

Internal CLI Shape

The CLI is the part developers will feel every day.

Keep commands predictable:

skillhub login
skillhub search api
skillhub show api-contract-review
skillhub install api-contract-review --agent codex
skillhub install api-contract-review --agent claude-code --global
skillhub list
skillhub outdated
skillhub update
skillhub remove api-contract-review

For repository operations:

skillhub repo list acme/payments-api
skillhub repo install acme/payments-api api-contract-review --open-pr
skillhub repo update acme/payments-api --open-pr
skillhub repo audit acme/payments-api

The CLI should support at least these target mappings:

agents:
  codex:
    project: ".agents/skills"
    global: "~/.codex/skills"
  claude-code:
    project: ".claude/skills"
    global: "~/.claude/skills"
  github-copilot:
    project: ".github/skills"
    global: "~/.copilot/skills"

When in doubt, prefer project install for team workflows and global install for personal workflows.

Webhooks And Indexing

The registry should update itself from GitHub events.

push to main
  Re-index registry.yaml and skills/**/SKILL.md
  Recompute content hashes
  Update search index
  Mark approved versions available

pull_request opened
  Run validation
  Comment with skill quality report
  Request owner/security review

pull_request merged
  Publish new version
  Notify subscribers

installation_repositories changed
  Refresh accessible repo list
  Update install availability

This gives you a nice operating loop:

Git remains source of truth
Web app remains discovery layer
CI remains quality gate
CLI remains installation layer

MVP Build Plan

If I were building this inside a company, I would ship it in six small releases.

Release 1: read-only catalog.

Private registry repo
registry.yaml
Skill parser
Search page
Skill detail page

Release 2: validation and review.

CI checks for SKILL.md
Dangerous-pattern scanner
CODEOWNERS
PR template
Status: draft, pilot, approved, deprecated

Release 3: local CLI install.

GitHub OAuth login
Short-lived download token
skillhub install
Target agent folder mapping
.skillhub.lock.json

Release 4: repo install PRs.

GitHub App installation
Repo picker
Branch creation
Copy skill folder
Open pull request

Release 5: update automation.

Outdated skill detection
Changelog rendering
Update PRs
Subscription notifications

Release 6: contribution workflow.

New skill form
Edit skill form
Generated branch and PR
Validation comments
Approval dashboard

That path lets the registry become useful before it becomes sophisticated.

The Review Workflow

A skill review should combine product review, engineering review, and security review.

Here is a lightweight flow:

Author opens PR with SKILL.md
        |
        v
CI validates structure and metadata
        |
        v
Owner reviews usefulness and scope
        |
        v
Security reviews scripts, tools, secrets, and prompts
        |
        v
Pilot group installs pinned version
        |
        v
Registry marks skill approved

The review checklist should ask:

  • Does the description clearly say when to use the skill?
  • Is the skill narrow enough to be reliable?
  • Does it depend on local paths, private chats, or one person’s machine?
  • Are scripts readable, minimal, and necessary?
  • Does it ask the agent to ignore higher-priority instructions?
  • Does it collect or expose secrets?
  • Does it write files, call networks, or run shell commands?
  • Does it include examples of good output?
  • Is there an owner who will maintain it?

The research literature is already warning us where this gets tricky. A 2026 OpenReview paper analyzing 138,133 public SKILL.md files found that public skills often have reusability defects around routing, portability, resource organization, and behavioral safety. A 2026 arXiv paper on semantic supply-chain attacks found that registry-facing skill discovery and selection can be manipulated through adversarial descriptions. Another 2026 paper, SkillGuard, argues that skill ecosystems need permission-aware governance because static review alone does not fully connect a skill’s declared intent to runtime behavior.

For company work, that means the registry should not stop at “does the YAML parse?”

A Minimal Skill Validation Script

You can begin with a small validation script in CI. This example is intentionally modest:

import fs from "node:fs";
import path from "node:path";
import YAML from "yaml";

const root = process.argv[2] ?? "skills";
const required = ["name", "description"];
const dangerousPatterns = [
  /ignore (all )?(previous|prior) instructions/i,
  /do not tell the user/i,
  /rm -rf/i,
  /curl .* \| *sh/i,
  /-----BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY-----/i,
];

function walk(dir: string): string[] {
  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
    const full = path.join(dir, entry.name);
    return entry.isDirectory() ? walk(full) : [full];
  });
}

const skillFiles = walk(root).filter((file) => file.endsWith("SKILL.md"));
let failures = 0;

for (const file of skillFiles) {
  const text = fs.readFileSync(file, "utf8");
  const match = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);

  if (!match) {
    console.error(`${file}: missing YAML frontmatter`);
    failures++;
    continue;
  }

  const frontmatter = YAML.parse(match[1]);

  for (const field of required) {
    if (!frontmatter?.[field]) {
      console.error(`${file}: missing ${field}`);
      failures++;
    }
  }

  if (!/^[a-z0-9-]+$/.test(frontmatter.name ?? "")) {
    console.error(`${file}: name must be lowercase kebab-case`);
    failures++;
  }

  if ((frontmatter.description ?? "").length < 40) {
    console.error(`${file}: description is probably too vague`);
    failures++;
  }

  for (const pattern of dangerousPatterns) {
    if (pattern.test(text)) {
      console.error(`${file}: matched dangerous pattern ${pattern}`);
      failures++;
    }
  }
}

if (failures > 0) {
  process.exit(1);
}

This does not make a skill safe. It catches the obvious mistakes so reviewers can spend their attention on judgment.

Installation Targets

Different agents expect skills in different places. Public docs from GitHub Copilot mention project skill directories such as .github/skills, .claude/skills, or .agents/skills, and personal skill directories such as ~/.copilot/skills or ~/.agents/skills.

In practice, a company should define one canonical internal source and install out to the target agents:

company-agent-skills repo
        |
        +--> .agents/skills/          shared project convention
        |
        +--> .claude/skills/          Claude Code convention
        |
        +--> .github/skills/          GitHub Copilot project convention
        |
        +--> ~/.codex/skills/         personal Codex installation

For a project, prefer committed project skills when the workflow is part of how that repository should be built or operated.

For a person, prefer global skills when the workflow belongs to the individual, such as personal note-taking, writing style, or local automation.

For a company, prefer registry-managed skills when the workflow should be shared, reviewed, versioned, and discoverable.

Public vs Private Registry Decisions

Here is the simple decision table:

QuestionPublic SkillPrivate Company Skill
Does it reveal internal process?NoMaybe
Does it mention private systems?NoYes
Can outside users benefit?YesUsually no
Needs company approval?OptionalYes
Needs access control?NoYes
Needs internal telemetry?Nice to haveImportant
Review styleOpen-source maintainer reviewProduct, engineering, security
Install sourcePublic GitHub or public registryPrivate Git, internal CLI, package registry

A good public skill teaches a general workflow.

A good private skill encodes the company’s actual operating knowledge.

For example, incident-postmortem could be public if it teaches a generic incident review format. It becomes private when it includes your severity levels, on-call escalation paths, internal status-page rules, and customer communication templates.

What PMs Should Care About

PMs do not need to maintain the registry, but they should care deeply about what goes into it.

Skills can encode product judgment:

  • how to write a launch plan
  • how to review customer-impacting migrations
  • how to prepare a release note
  • how to evaluate support-ticket themes
  • how to turn discovery notes into acceptance criteria
  • how to decide whether a feature needs a staged rollout

The registry becomes a memory layer for how the company likes work to happen.

That is powerful. It is also why skills should be readable by non-authors. If a PM cannot understand the workflow by reading SKILL.md, the skill is probably too magical.

The Operating Model

The healthiest company registry has a few boring rules:

  • Every skill has an owner.
  • Every approved skill has a version.
  • Every risky skill has documented permissions.
  • Every script has a reason to exist.
  • Every install command can pin a version or commit.
  • Every deprecated skill has a replacement or removal date.
  • Every company-critical skill has examples and tests.

The registry should expose this as metadata:

name: incident-postmortem
owner: sre-platform
version: 2.1.0
status: approved
risk: medium
requires_review_from:
  - sre-platform
  - security
tested_agents:
  - codex
  - claude-code
  - github-copilot
last_reviewed: "2026-06-09"

You can render the metadata into a small internal site:

Skill                  Owner             Status      Agents
--------------------   ---------------   ---------   -------------------------
incident-postmortem    sre-platform      approved    codex, claude-code
api-contract-review    platform-api      approved    codex, copilot
billing-migration      payments          pilot       codex

This is the collaborative space: not a chat thread full of clever prompts, but a visible catalog of reviewed operational knowledge.

Start small.

Phase 1: collect the skills that already exist.

Find local SKILL.md files
Normalize names and descriptions
Move shared candidates into a private repo
Add CODEOWNERS
Add CI validation

Phase 2: publish the internal catalog.

Generate registry.yaml
Create a searchable docs page
Add examples and install commands
Mark skills as draft, pilot, approved, or deprecated

Phase 3: automate installation.

Build a small internal CLI
Support install by name and version
Write into .agents/skills or agent-specific directories
Record anonymous install events

Phase 4: add governance.

Require owner approval
Require security review for scripts or network access
Support rollback to previous versions
Track usage, stale skills, and failed activations

Here is the end-state flow:

Team authors skill
      |
      v
Pull request validates and reviews it
      |
      v
Registry publishes approved version
      |
      v
Developers install it into project or global agent folders
      |
      v
Usage and feedback create the next improvement PR

Gaps To Watch

The skill ecosystem is moving quickly, and a few gaps are still unresolved.

First, cross-agent compatibility is still uneven. The SKILL.md shape is portable, but different agents may support different directories, tool permissions, install flows, and runtime behaviors.

Second, quality signals are immature. Stars, install counts, and popularity help discovery, but they do not prove a skill is correct, safe, or maintained.

Third, private registry standards are still forming. You can build a very useful registry with Git and CI, but there is not yet one universal enterprise model for permissions, signatures, provenance, and runtime enforcement.

Fourth, security scanning is necessary but incomplete. A clean static scan does not guarantee safe behavior after the skill enters a live agent session.

Fifth, teams need lifecycle discipline. The hard part is not creating ten skills. The hard part is keeping fifty skills current after the organization, APIs, tools, and policies change.

Recommended Next Sections For A Future Article

This article gives the architecture. A follow-up could go deeper into:

  • a full registry.yaml schema
  • signing and verifying skill releases
  • measuring whether a skill actually improves agent output
  • comparing skill registries with MCP servers and traditional plugins
  • designing a permission model for skills with scripts and network access
  • converting existing team docs into high-quality SKILL.md files
  • building an evaluation suite that tests whether skills trigger at the right time

Final Take

Treat skills as code-adjacent artifacts.

They are readable like docs, reusable like packages, and operational like automation. That makes them a strange little hybrid, but also a very useful one.

Public directories like skills.sh show the discovery pattern. A company registry should add the missing company layer: trust, ownership, review, rollout, and maintenance.

If you do only one thing this month, do this:

Create a private company-agent-skills repo.
Add three useful skills.
Add owners and review.
Install them in one pilot team.
Measure what breaks.

That is enough to turn scattered prompts into a collaborative skill system.

Source List

  1. Anthropic: Equipping agents for the real world with Agent Skills - explains the Agent Skills format, SKILL.md, metadata, and progressive disclosure.
  2. GitHub Docs: Adding agent skills for GitHub Copilot - documents SKILL.md frontmatter, project and personal skill locations, and optional scripts/resources.
  3. OpenAI skills catalog for Codex - shows Codex skill installation patterns using $skill-installer, curated skills, experimental skills, and GitHub directory URLs.
  4. skills.sh documentation - describes skills as reusable AI-agent capabilities, the npx skills add flow, leaderboard telemetry, badges, and security caveats.
  5. skills.sh directory - public directory of indexed agent skills and install-count style discovery.
  6. SkillsGate: The open marketplace for AI agent skills - describes public discovery as powered by skills.sh, an open index of skills from GitHub.
  7. Vercel changelog: Introducing skills, the open agent skills ecosystem - describes the cross-agent npx skills ecosystem and supported agent targets.
  8. What Keeps Agent Skills from Being Reusable? Evidence from 138K SKILL.md Files - analyzes public SKILL.md reuse defects across routing, portability, resource organization, and safety.
  9. Under the Hood of SKILL.md: Semantic Supply-chain Attacks on AI Agent Skill Registry - studies registry-facing attack surfaces in discovery, selection, and installation.
  10. SkillGuard: A Permission Framework for Agent Skills - proposes permission-centered governance for agent skills and runtime behavior.
  11. SkillReg: Private Registry for AI Agent Skills - an example of the emerging private-registry product category for sharing and governing company skills.
  12. LoadoutHQ: Private skills registry for enterprise AI agents - another example of private skill registry positioning around governed folders and company distribution.
  13. GitHub Docs: REST API endpoints for GitHub Apps - documents GitHub App installations, repository selection, permissions, and installation access token URLs.
  14. GitHub Docs: REST API endpoints for repository contents - documents create/update file operations and the required contents permissions for GitHub App installation tokens.
  15. GitHub Docs: REST API endpoints for pull requests - documents creating pull requests and the required pull request permissions for GitHub App installation tokens.