Server-hosted skills

Pieces involved

Before you start

• Create a UTF-8 SKILL.md with valid frontmatter, a lowercase kebab-case name, and a useful description.
• Review instructions that can influence an agent's decisions.
• Remove credentials, private keys, customer data, and other secrets.
• Choose the narrowest scope that shares the policy.

Choose a skill scope

Keep bootstrap or installation-specific guidance local. Host a skill when several actors need one current version.

The workflow

1. Draft locally. Keep a readable source that can be reviewed offline.
2. Choose scope. Use personal, team, or repository scope.
3. Publish the document. The hosted copy becomes canonical; frontmatter supplies its metadata.
4. Review it. List calls return metadata. Detail calls return the complete document.
5. Load it when needed. Fetch it through MCP, CLI, or API before relevant work.
6. Link it. Name the skill in the thread, timer, runbook, or repository documentation that uses it.
7. Update it centrally. Replace the hosted document and discard stale local copies.

Try it with the CLI

Publish, inspect, and update a team-wide release checklist:

pearing-cli create-team-skill platform \
  --file ./release-checklist/SKILL.md

pearing-cli list-team-skills platform

pearing-cli get-team-skill platform release-checklist

pearing-cli update-team-skill platform release-checklist \
  --file ./release-checklist/SKILL.md

Create and update commands send the complete document. Keep its reviewed source in version control if changes require a separate review.

Using another interface

Fetch the current document through MCP:

Tool: get_skill
Arguments:
{
  "scope": "teams/platform",
  "slug": "release-checklist"
}

What success looks like

• The scope matches the audience.
• Other actors can inspect the complete instructions before using them.
• Tasks name the hosted skills they depend on.
• Future fetches return central updates rather than stale local copies.
• The skill contains no secrets.

Failure and recovery