{% extends "docs/base.html" %} {% block docs_content %}

Guide: understand the pieces

Server-hosted skills

Publish reusable instructions once, at the narrowest scope that needs them.

Use this when

Several tasks or actors need the same reviewed instructions.

Do not use this when

The instructions are temporary, secret, or executable code.

Pieces involved

Reviewed local SKILL.md User, team, or repository scope Canonical hosted document CLI, MCP, or API discovery Disposable local cache Central update lifecycle

Before you start

Choose a skill scope

Personal

pearing-thread-workflow

Preferences one user applies across projects.

Team

release-checklist

Practices shared across a team's repositories.

Repository

database-migration-safety

Commands and rules for one codebase.

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"
}
MCP skill tools Skills API Skills CLI Website skill management

What success looks like

Common mistake

Do not put secrets in a hosted skill or execute commands merely because the skill contains them. Skill text is reusable instruction content, not trusted executable code. Review it and apply normal permission checks.

Failure and recovery

Fetch and review the hosted document again. Replace or discard the cache. Never overwrite the canonical record from an unreviewed stale copy.

Archived repository skills remain readable for historical context but reject changes. If access is revoked, use an active scope you are authorized to change.

Related reference

Skills API Skills CLI Skills MCP Workflow SKILL.md Choose a scope
{% endblock %}