Publish Skill

Complete release pipeline for Battle Skills — validate, catalog, changelog, version bump, git tag, and npm publish in one go.

When to Use This Skill

• After creating a new skill with

  create-skill

• After modifying an existing skill's SKILL.md or references
• When you want to release a new version to npm
• User says "publish", "release", "deploy to npm", "bump version"

When NOT to Use This Skill

• You're still writing the skill content → finish first, then publish
• You only want to validate without publishing → run

  python3 scripts/validate_skills.py

  directly

Pre-Flight Checklist

Before starting the pipeline, confirm:

• All skill changes are saved
• You are in the repo root (

  battle-skills/

  )

• npm whoami

  returns a valid npm user
• No uncommitted changes that shouldn't be included

Pipeline Steps

Step 1 — Validate All Skills

python3 scripts/validate_skills.py

Expected: All skills pass with

✓ OK

[ERROR]

⚠ WARN

[!CAUTION] Do NOT proceed if any skill has

[ERROR]

. Fix the error first.

Step 2 — Generate Catalog

python3 scripts/gen_catalog.py

Expected:

skills_index.json

CATALOG.md

Verify: Open

CATALOG.md

Step 3 — Update CHANGELOG.md

Add a new version section above the previous version. Follow Keep a Changelog format. Always write in English.

## [X.Y.Z] — YYYY-MM-DD

### Added

- `skill-name` — One-line description of the new skill.

### Changed

- Description of what changed in existing skills.

### Fixed

- Description of bug fixes.

Rules:

1. Read current version from

   package.json

   →

   "version"

   field
2. Bump the patch number (e.g.,

   1.0.6

   →

   1.0.7

   ) for new skills or fixes
3. Bump the minor number (e.g.,

   1.0.7

   →

   1.1.0

   ) for breaking changes or major features
4. Write all entries in English
5. Update the comparison links at the bottom of CHANGELOG.md:

[Unreleased]: https://github.com/QuocTang/battle-skills/compare/vX.Y.Z...HEAD
[X.Y.Z]: https://github.com/QuocTang/battle-skills/compare/vPREV...vX.Y.Z

Step 4 — Bump Version in package.json

Update the

"version"

package.json

# Example: bump patch version
npm version patch --no-git-tag-version

Or manually edit

package.json

Verify:

cat package.json | grep version

Step 5 — Git Commit & Tag

# Stage all changes
git add .

# Commit with conventional message
git commit -m "feat(skill): add <skill-name> — release vX.Y.Z"

# Create annotated tag
git tag -a vX.Y.Z -m "Release vX.Y.Z"

# Push to remote
git push origin main --tags

Commit message convention:

feat(skill): add <name>

improve(skill): update <name>

fix(skill): fix <name>

feat(skill): add <name> — release vX.Y.Z

Step 6 — Publish to npm

npm publish

Expected: Output shows

+ battle-skills@X.Y.Z

Verify after publish:

npm info battle-skills version

Should return the new version number.

Quick Reference — Full Pipeline

For a fast copy-paste workflow when everything is ready:

# 1. Validate
python3 scripts/validate_skills.py

# 2. Generate catalog
python3 scripts/gen_catalog.py

# 3. Update CHANGELOG.md (manual step — edit the file)

# 4. Bump version
npm version patch --no-git-tag-version

# 5. Commit & tag
git add .
git commit -m "feat(skill): add <skill-name> — release v$(node -p 'require(\"./package.json\").version')"
git tag -a "v$(node -p 'require("./package.json").version')" -m "Release v$(node -p 'require("./package.json").version')"
git push origin main --tags

# 6. Publish
npm publish

Troubleshooting

npm ERR! 403

npm login

npm ERR! version already exists

npm version patch

[ERROR]

git push

git pull --rebase origin main

python3 scripts/gen_catalog.py

Anti-Patterns (Avoid)

npm publish