Maintaining Your Skill

Publishing is the beginning, not the end. Skills need updates as the agent runtime evolves, user feedback accumulates, and the SKILL.md spec adds new features.

Versioning

Follow semantic versioning:

Change type	Version bump	Example
Fix a typo or clarify wording	Patch	1.0.0 → 1.0.1
Add new examples or optional behavior	Minor	1.0.0 → 1.1.0
Rewrite instructions or change trigger	Major	1.0.0 → 2.0.0

When you push a new version to GitHub, the marketplace indexer detects the version change and re-scores the updated skill automatically. No manual resubmission needed.

Pushing Updates

# Make your changes to SKILL.md
# Bump the version field in frontmatter
git add SKILL.md
git commit -m "fix: clarify trigger wording (1.0.1)"
git push

The marketplace syncs with your repo within 15 minutes of a push to your default branch.

CI Validation

Add automatic validation to your GitHub Actions workflow to catch schema errors before they reach the marketplace:

# .github/workflows/validate-skills.yml
name: Validate Skills

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @hordago/skill-validator ./ --recursive

This runs the same validator used by the marketplace auto-scorer, so you see issues locally before pushing.

Deprecating a Skill

If you’ve superseded a skill with a better one, deprecate the old version rather than deleting it. Users who have the old skill installed get a migration notice.

---
name: old-skill
# ... other fields ...
deprecated: true
deprecated_by: "new-skill"
---

Push the update to GitHub. The marketplace will:

1. Remove the skill from search results
2. Show a deprecation notice on the skill’s detail page
3. Notify installed users to switch to new-skill

Do not delete the repository or SKILL.md file — the runtime needs the file present to serve the deprecation notice to existing users.

Responding to User Feedback

User ratings and comments appear in your marketplace dashboard. Common patterns worth acting on:

• “Trigger not firing” — Your trigger description may be too narrow. Broaden it and bump a patch version.
• “Instructions unclear” — Add examples or numbered steps to the body.
• “Conflicts with X skill” — Add a note to your trigger explaining when NOT to use your skill.

Archiving

If you no longer maintain a skill and no replacement exists, archive it:

---
name: my-skill
deprecated: true
---

Without a deprecated_by field, the skill is marked archived rather than redirected. Archived skills are hidden from search but remain accessible by direct URL.