Claude Code Plugins

Community-maintained marketplace

Feedback

project-standardization

@j0KZ/mcp-agents
0
0

Guides correct usage of @j0kz/mcp-agents standardization and automation scripts including version.json single source of truth, test count automation, URL casing rules, and critical workflow pattern...

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name project-standardization
description Guides correct usage of @j0kz/mcp-agents standardization and automation scripts including version.json single source of truth, test count automation, URL casing rules, and critical workflow pattern...

Project Standardization & Automation for @j0kz/mcp-agents

Ensure consistency across monorepo using automated scripts and established patterns.

4 Critical Rules (NEVER VIOLATE)

Rule 1: version.json is Single Source of Truth

  • ❌ NEVER manually edit package.json versions
  • ✅ ALWAYS use: npm run version:sync
  • 11 packages must stay in sync

Rule 2: URL Casing Rules

  • GitHub: j0KZ (capital K, Z)
  • npm: @j0kz (lowercase)
  • Mixing breaks links and installations

Rule 3: Test Count Automation

  • ❌ NEVER manually edit test badges
  • ✅ ALWAYS use: npm run update:test-count
  • Currently: 632 tests passing

Rule 4: @latest in Documentation

  • ❌ WRONG: npx @j0kz/mcp-agents@1.0.36
  • ✅ RIGHT: npx @j0kz/mcp-agents@latest

Quick Command Reference

# Version management
npm run version:sync              # Sync all versions from version.json
npm run version:check-shared      # Verify shared package versions

# Testing
npm test                          # Run all tests
npm run update:test-count         # Update test count in docs

# Building
npm run build                     # Build all packages
npm run dev                       # Watch mode

# Publishing
npm run publish-all               # Publish all packages

Version Management Workflow

Quick Start: New Release

# 1. Update version.json
echo '{"version": "1.1.0"}' > version.json

# 2. Sync and build
npm run version:sync
npm run version:check-shared
npm test
npm run build

# 3. Publish
npm run publish-all
cd installer && npm publish && cd ..

# 4. Git operations
git add . && git commit -m "release: v1.1.0"
git tag v1.1.0 && git push origin main --tags

For detailed release workflow with all steps:

cat .claude/skills/project-standardization/references/version-management-guide.md

Test Count Management

# After adding/removing tests
npm run update:test-count

# Updates 3 files automatically:
# - README.md badge
# - wiki/Home.md badge and table
# - CHANGELOG.md metrics

For test automation details and patterns:

cat .claude/skills/project-standardization/references/test-automation-guide.md

URL & Link Standards

Critical: GitHub uses j0KZ, npm uses @j0kz

For complete URL standards and examples:

cat .claude/skills/project-standardization/references/url-standards-guide.md

tools.json Management

Location: tools.json at repository root - Single source of truth for all MCP tool metadata

When to update:

  • Adding new MCP tool
  • Changing tool features/descriptions
  • Adding new category

Structure includes: tool id, name, package, description, category, features, wikiPage

Workspace Management

Adding New Package

mkdir packages/new-tool
npm install                       # Auto-discovers workspace
npm ls --workspaces              # Verify recognized

Dependency Installation

npm install typescript -w packages/new-tool  # Specific workspace
npm install typescript --workspaces          # All workspaces
npm install vitest -D                        # Root only

Common Mistakes and Quick Fixes

Mistake Fix
Manually edited package.json version npm run version:sync
Hardcoded version instead of @latest Use @latest in docs
Wrong URL casing (GitHub/npm) GitHub: j0KZ, npm: @j0kz
Manually updated test count npm run update:test-count
Forgot to sync after version.json change Always run version:sync first

Validation & Checklists

For complete validation checklists (pre-commit, pre-publish, post-publish):

cat .claude/skills/project-standardization/references/validation-checklists.md

Key File Locations

version.json                      # Single source of truth for versions
tools.json                        # MCP tool metadata
scripts/sync-versions.js          # Version sync automation
scripts/update-test-count.js      # Test count automation
scripts/enforce-shared-version.js # Shared version validation

Getting Help

# Check current state
cat version.json                  # Current version
npm run version:check-shared      # Package consistency
git status                        # Uncommitted changes

# Review scripts
ls scripts/                       # List all automation
cat scripts/sync-versions.js      # Read script details

Related Skills

  • monorepo-package-workflow: Creating new MCP packages
  • release-publishing-workflow: Complete release process
  • git-pr-workflow: Git operations and PR creation

Additional Resources