Publishing Guide#

This guide walks you through creating a Skill, validating it, and publishing it to Loot Protocol so others can discover and install it.

Skills only, for now. Loot Protocol currently supports publishing Skills. MCP server support is coming soon (see the note at the end of this page).

What a Skill Is#

A Skill is a single-purpose instruction set that teaches Claude how to perform a task. It is packaged as an archive (.zip or .tar.gz, ≤ 5 MB) and hosted by Loot Protocol. See the Extension Types reference for the full specification.

File Structure#

my-skill/
├── SKILL.md          # REQUIRED - instructions with YAML frontmatter
├── reference.md      # optional
├── examples.md       # optional
└── scripts/          # optional
    └── *.sh|*.py|*.js

SKILL.md must contain:

• YAML frontmatter between --- markers with a description field (required) and optionally a name field (lowercase, hyphens only, max 64 chars)
• A body with at least 10 characters of instruction content

Example SKILL.md:

---
description: Performs thorough code reviews focusing on correctness, performance, and maintainability
name: code-review
---
 
When asked to review code, follow these steps:
 
1. Read the entire file or diff provided
2. Check for correctness issues (logic errors, off-by-one, null safety)
3. Evaluate performance (unnecessary allocations, O(n^2) where O(n) is possible)
4. Assess maintainability (naming, structure, documentation)
5. Provide specific, actionable feedback with line references

Validation Rules#

Every submission is validated before it is accepted:

• Archive must be a .zip or .tar.gz file
• No path traversal (../) is allowed in any file paths
• SKILL.md must exist at the archive root
• Must have valid YAML frontmatter with a non-empty description
• name field (if present) must be lowercase, hyphens only, max 64 characters
• Body must contain at least 10 characters
• Total size must be under 5 MB

Pre-Publish Checklist#

Before publishing, validate your skill locally:

# Validate your skill without uploading
loot validate ./my-skill --type skill
 
# Or let the CLI auto-detect the type
loot validate ./my-skill

The CLI runs the same validation logic the server uses, giving you fast feedback before you submit.

Publish via the Web UI#

1. Sign in at lootprotocol.com with your GitHub account
2. Navigate to the Publish page and select Skill
3. Upload your archive -- drag and drop a .zip or .tar.gz file, or use the file picker
4. Review validation results -- the server validates immediately. If there are errors, you see exactly what went wrong (e.g., "Missing SKILL.md")
5. Fill in listing details:
   • Display name
   • Category (Development Tools, Productivity, Testing & QA, Security, Database & Backend, DevOps & Deployment, Design & Frontend, Learning & Docs, Integrations, Other)
   • Tags (up to 5)
   • Short description
6. Submit -- your package is uploaded, metadata is saved, and the extension is listed immediately

Publish via the CLI#

Step 1: Authenticate#

loot login

This opens your browser for GitHub OAuth. Credentials are saved to ~/.lootprotocol/config.json.

Step 2: Navigate to Your Skill#

cd my-skill/

Step 3: Publish#

loot publish

The CLI will:

1. Package the current directory as a .tar.gz archive
2. Run local validation (same rules as the server)
3. If validation passes, prompt you for metadata (display name, category, tags)
4. Upload to the Loot Protocol API
5. The server re-validates and stores the package

To skip the interactive prompts (e.g., in CI), create a lootprotocol.json file in your skill root and pass --non-interactive:

{
  "type": "skill",
  "displayName": "Code Review Assistant",
  "category": "development-tools",
  "tags": ["code-review", "quality", "best-practices"]
}

loot publish --non-interactive

Updating a Skill#

To publish a new version, run loot publish again from the updated skill directory (or re-upload via the web UI). The server recognizes the extension by its slug and creates a new version. Previous versions are retained (immutable) in storage.

You can also link a GitHub repo so new releases publish automatically -- see loot link-repo and loot sync.

Troubleshooting#

"Validation failed" errors#

Run loot validate to see specific error messages. Common issues:

• Missing SKILL.md
• Invalid YAML frontmatter
• Missing description in frontmatter
• name field not in kebab-case
• Archive exceeds the 5 MB size limit

"Authentication required"#

Your token may have expired. Run loot login again to re-authenticate.

MCP Servers (coming soon)#

Publishing MCP (Model Context Protocol) servers is not available yet. When it ships, you'll be able to register an externally-hosted MCP server's connection details through the web UI -- no archive upload required. This guide will be updated at that time.

Next Steps#

• Extension Types -- the full Skill specification
• CLI Reference -- complete documentation for all CLI commands