This skill covers the end-to-end workflow for publishing skill files to SkillDB — from preparing your skill for release, through validation and review, to making it available for discovery by users and AI agents. It addresses the SkillDB CLI commands, quality gates, publishing best practices, and post-publish monitoring.

## Key Points

1. Verify all skills in the pack:
2. Check pack cohesion:
3. Create pack metadata:
4. Version the pack:
- Publishing a skill or skill pack for the first time
- Setting up automated publishing pipelines
- Managing the lifecycle of published skills
- Responding to feedback on published skills
- Establishing publishing workflows for a team
- Planning a release of updated skill content

Skill Publishing Workflow

Purpose

This skill covers the end-to-end workflow for publishing skill files to SkillDB — from preparing your skill for release, through validation and review, to making it available for discovery by users and AI agents. It addresses the SkillDB CLI commands, quality gates, publishing best practices, and post-publish monitoring.

Publishing Overview

Workflow Stages

Skill Publishing Pipeline:
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  Write   │──→│ Validate │──→│ Publish  │──→│ Monitor  │
│          │   │          │   │          │   │          │
└──────────┘   └──────────┘   └──────────┘   └──────────┘
     │              │              │              │
   Author        Quality        Release       Feedback
   creates       gates          to SkillDB    and iterate
   skill file    pass/fail      registry

Roles:
├── Author: Writes and maintains the skill
├── Reviewer: Validates accuracy and quality (can be same person)
├── Publisher: Has credentials to push to SkillDB
└── Consumer: Users and AI agents who use the skill

Pre-Publish Preparation

Final Checks

Pre-Publish Checklist:
□ Frontmatter is complete and valid
  ├── title: Specific, searchable, 4-12 words
  ├── category: Matches directory name, kebab-case
  ├── tags: 3-8 relevant keywords, lowercase
  └── version: Correct semver (increment from last published)

□ Content passes quality review
  ├── Purpose is clear and specific
  ├── All code examples tested and working
  ├── Instructions are complete and unambiguous
  ├── "When to Apply" section is present
  ├── No TODO/placeholder content
  └── File is 100-600 lines

□ Metadata is correct
  ├── Version incremented appropriately
  ├── Tags are from controlled vocabulary (if applicable)
  └── Category exists in target registry

□ Dependencies verified
  ├── Referenced skills exist
  ├── External links are valid
  └── Required tools/versions are current

Preparing a Skill Pack

Pack-Level Preparation:
1. Verify all skills in the pack:
   └── Each skill passes individual quality checklist

2. Check pack cohesion:
   ├── All skills share the same category
   ├── Cross-references between skills are valid
   ├── No duplicate coverage
   ├── No significant gaps
   └── Consistent terminology across all skills

3. Create pack metadata:
   └── Description of the pack's scope and audience
   └── List of included skills
   └── Recommended reading order (if applicable)

4. Version the pack:
   └── Pack version independent of skill versions
   └── Increment when skills are added/removed

Using the SkillDB CLI

Authentication

# Log in to SkillDB
skilldb login
# Opens browser for authentication
# Stores credentials locally

# Verify authentication
skilldb whoami
# Output: Logged in as <username>

# Check your publishing permissions
skilldb auth check
# Output: Can publish to: [list of allowed categories]

Validation

# Validate a single skill file
skilldb validate skills/my-category/my-skill.md
# Output:
# ✓ Frontmatter valid
# ✓ Structure valid
# ✓ Content checks passed
# ✓ Ready to publish

# Validate all skills in a directory
skilldb validate skills/my-category/
# Output:
# Validating 15 files...
# ✓ 14 passed
# ✗ 1 failed: missing-section.md
#   - Missing "When to Apply" section
#   - Code block on line 45 has no language specifier

# Validate with strict mode (additional checks)
skilldb validate --strict skills/my-category/my-skill.md
# Also checks:
# - External link validity
# - Spelling (common technical terms)
# - Tag vocabulary compliance

Publishing

# Publish a single skill
skilldb publish skills/my-category/my-skill.md
# Output:
# Validating... ✓
# Publishing my-skill v1.0.0 to my-category...
# ✓ Published successfully
# URL: https://skilldb.dev/skills/my-category/my-skill

# Publish all skills in a pack
skilldb publish skills/my-category/
# Output:
# Validating 15 files... ✓ All passed
# Publishing my-category pack (15 skills)...
# ✓ 12 new skills published
# ✓ 3 skills updated (version changed)
# Pack URL: https://skilldb.dev/packs/my-category

# Publish with dry run (preview without publishing)
skilldb publish --dry-run skills/my-category/
# Output:
# [DRY RUN] Would publish:
# - my-skill.md (NEW, v1.0.0)
# - updated-skill.md (UPDATE, v1.0.0 → v1.1.0)
# - unchanged-skill.md (SKIP, no version change)

# Publish with specific version override
skilldb publish --version 2.0.0 skills/my-category/my-skill.md
# Overrides frontmatter version (use sparingly)

Managing Published Skills

# List your published skills
skilldb list --mine
# Output:
# my-category/skill-a  v1.2.0  published 2025-06-15
# my-category/skill-b  v1.0.0  published 2025-06-10
# my-category/skill-c  v2.1.0  published 2025-07-01

# View skill details
skilldb info my-category/skill-a
# Output:
# Title: "Skill A Title"
# Version: 1.2.0
# Published: 2025-06-15
# Downloads: 342
# Rating: 4.5/5 (23 ratings)

# Unpublish a skill (remove from registry)
skilldb unpublish my-category/skill-a
# Requires confirmation
# Note: Does not delete, marks as unlisted

# Deprecate a skill
skilldb deprecate my-category/skill-a \
  --successor my-category/skill-a-v2 \
  --message "Replaced by v2 with updated approach"

Publishing Best Practices

Version Management

Version Increment Decision:
├── First publish: 1.0.0
├── Fixed a typo or broken link: 1.0.1 (PATCH)
├── Added new section or examples: 1.1.0 (MINOR)
├── Changed recommended approach: 2.0.0 (MAJOR)
└── Rule: When in doubt, use MINOR

Pre-release Versions (for testing):
├── 1.0.0-beta.1: Beta testing
├── 1.0.0-rc.1: Release candidate
└── Not shown in default search results
└── Useful for getting feedback before official release

Release Notes

Include release notes with significant updates:

skilldb publish --notes "Added TypeScript examples,
updated for React 19, fixed authentication code example"
skills/react-skills/react-auth.md

Release Note Guidelines:
├── What changed (briefly)
├── Why it changed (if not obvious)
├── What to look for (if migrating from previous version)
└── Keep under 3 sentences for most updates

Timing and Batching

Publishing Strategy:
├── Publish individual fixes immediately (PATCH updates)
├── Batch minor updates weekly (MINOR updates)
├── Major releases with announcement (MAJOR updates)
├── New pack: Publish all skills together (cohesive launch)
└── Pack update: Publish changed skills, keep unchanged as-is

Avoid:
├── Publishing untested skills "to fix later"
├── Publishing during peak usage times without testing
├── Publishing major changes on Friday (no one monitors weekends)
└── Publishing partial packs (all or nothing for first release)

Post-Publish Monitoring

Tracking Skill Performance

Metrics to Monitor:
├── Discovery rate: How often is this skill found in searches?
├── Load rate: How often is this skill loaded by agents?
├── Completion rate: When loaded, does it lead to task completion?
├── Feedback: User ratings and comments
├── Issue reports: Bugs or inaccuracies reported
└── Version adoption: Are users on the latest version?

Monitoring Cadence:
├── First 48 hours after publish: Check for critical issues
├── First week: Review initial feedback and metrics
├── Monthly: Check for staleness, declining metrics
├── Quarterly: Full review and update cycle

Responding to Feedback

Feedback Response Protocol:

Bug report (skill has incorrect information):
├── Severity: HIGH
├── Response time: Same day
├── Action: Fix and publish PATCH version
├── Communication: Acknowledge report, publish fix

Feature request (skill missing coverage):
├── Severity: MEDIUM
├── Response time: Within 1 week
├── Action: Evaluate, add if valuable, publish MINOR version
├── Communication: Acknowledge, set expectation

Style/preference feedback:
├── Severity: LOW
├── Response time: Next update cycle
├── Action: Consider in aggregate (many voices > one)
├── Communication: Thank the user

Negative rating without explanation:
├── Action: Review skill against quality checklist
├── Look for common issues: outdated, unclear, incomplete
├── If skill passes quality check: Accept the rating
├── If issues found: Fix and update

Automation

CI/CD for Skills

# Example GitHub Actions workflow for skill publishing
name: Publish Skills
on:
  push:
    branches: [main]
    paths: ['skills/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install SkillDB CLI
        run: npm install -g @skilldb/cli
      - name: Validate all skills
        run: skilldb validate --strict skills/

  publish:
    needs: validate
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Install SkillDB CLI
        run: npm install -g @skilldb/cli
      - name: Authenticate
        run: skilldb login --token ${{ secrets.SKILLDB_TOKEN }}
      - name: Publish changed skills
        run: skilldb publish --changed skills/
        # --changed flag only publishes skills with version changes

# Pre-commit hook for skill validation
#!/bin/bash
# .git/hooks/pre-commit

# Find changed skill files
CHANGED=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$' | grep '^skills/')

if [ -n "$CHANGED" ]; then
  echo "Validating changed skill files..."
  for file in $CHANGED; do
    skilldb validate "$file"
    if [ $? -ne 0 ]; then
      echo "Validation failed for $file"
      echo "Fix issues before committing."
      exit 1
    fi
  done
  echo "All skill files valid."
fi

Checklist Summary

Publishing Checklist (copy and use):

Before Publishing:
□ Skill passes quality checklist
□ All code examples tested
□ Version incremented from last publish
□ Tags from controlled vocabulary
□ skilldb validate passes
□ Dry run reviewed (skilldb publish --dry-run)

Publishing:
□ Published to correct category
□ Release notes included (for MINOR+)
□ Verified skill appears in search
□ Tested skill loading in an agent

After Publishing:
□ Monitor first 48 hours for issues
□ Review initial feedback within 1 week
□ Schedule next review (3-6 months)

When to Apply This Skill

Use this skill when:

• Publishing a skill or skill pack for the first time
• Setting up automated publishing pipelines
• Managing the lifecycle of published skills
• Responding to feedback on published skills
• Establishing publishing workflows for a team
• Planning a release of updated skill content