ship-clean-code

ship-code

Ship better code with AI. An open-source collection of skills, agents, and workflows for AI-assisted software development.

Built on the Agent Skills open standard and the Claude Code Skills 2.0 format.

Featured Skill: ship-clean-code

Write cleaner, more maintainable code across Python, TypeScript/JavaScript, and Java. Combines established clean code principles with modern best practices.

What it does:

• Writing mode — Silently applies clean code principles when generating code
• Review mode — Produces structured code reviews with priority-ranked findings (P1-Bugs through P7-Style)
• Language-aware — Auto-detects Python, TypeScript, or Java and loads language-specific idioms

What it covers:

• 12 core principles (naming, functions, classes, SRP, error handling, DRY, and more)
• 66 cataloged code smells with detection and fix guidance
• Logging & observability, testing best practices, quality gates
• Before/after examples for each language
• Pragmatism guidelines (won't rewrite code you didn't ask it to touch)

Installation

Option 1: Add as a marketplace (recommended — get all current and future skills)

This repo is a Claude Code plugin marketplace. Add it once and get access to all skills — including new ones as they're released:

# In Claude Code, run:
/plugin marketplace add ship-it-ops/ship-code

# Then install any skill from the marketplace:
/plugin install ship-clean-code@ship-code

# To see all available skills:
/plugin marketplace list ship-code

To auto-update when we release new skills or improvements:

/plugin marketplace update ship-code

You can also configure your project to recommend this marketplace to your team. Add to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "ship-code": {
      "source": {
        "source": "github",
        "repo": "ship-it-ops/ship-code"
      }
    }
  }
}

Option 2: npx (one command, single skill)

Using Vercel's skills CLI:

# Install to your current project
npx skills add ship-it-ops/ship-code --skill ship-clean-code

# Install globally (available in all projects)
npx skills add ship-it-ops/ship-code --skill ship-clean-code -g

# Install to a specific agent (Claude Code, Cursor, Codex, etc.)
npx skills add ship-it-ops/ship-code --skill ship-clean-code -a claude-code

Option 3: npx add-skill (multi-agent)

Using add-skill to install across multiple agents at once:

# Auto-detects your installed agents and installs to all of them
npx add-skill ship-it-ops/ship-code --skill ship-clean-code

# Install to specific agents
npx add-skill ship-it-ops/ship-code --skill ship-clean-code -a claude-code -a cursor

# Non-interactive (great for dotfiles / CI)
npx add-skill ship-it-ops/ship-code --skill ship-clean-code -g -y

Option 4: Copy into your project

# Clone and copy
git clone https://github.com/ship-it-ops/ship-code.git
cp -r ship-code/skills/ship-clean-code/ your-project/.claude/skills/ship-clean-code/

Option 5: Install globally (all projects)

git clone https://github.com/ship-it-ops/ship-code.git
mkdir -p ~/.claude/skills
cp -r ship-code/skills/ship-clean-code/ ~/.claude/skills/ship-clean-code/

Option 6: Symlink for automatic updates

# Clone somewhere permanent
git clone https://github.com/ship-it-ops/ship-code.git ~/ship-code

# Symlink into your project (stays in sync with git pull)
ln -s ~/ship-code/skills/ship-clean-code/ your-project/.claude/skills/ship-clean-code

# Or symlink globally
mkdir -p ~/.claude/skills
ln -s ~/ship-code/skills/ship-clean-code/ ~/.claude/skills/ship-clean-code

Option 7: Direct download (no clone, no npm)

# Download just the ship-clean-code skill using curl + tar
mkdir -p your-project/.claude/skills/ship-clean-code
curl -sL https://github.com/ship-it-ops/ship-code/archive/refs/heads/main.tar.gz \
  | tar xz --strip-components=3 -C your-project/.claude/skills/ship-clean-code \
  "ship-code-main/skills/ship-clean-code"

Verify installation

# In Claude Code, type / and look for ship-clean-code
# Or run:
ls ~/.claude/skills/ship-clean-code/SKILL.md 2>/dev/null \
  || ls .claude/skills/ship-clean-code/SKILL.md 2>/dev/null \
  && echo "Installed!" || echo "Not found"

Usage

Once installed, the skill works automatically in Claude Code:

# The skill auto-invokes when you write or review Python/TS/Java code
claude "write a user authentication service in Python"

# Explicitly invoke for a code review
claude "/ship-clean-code review src/services/payment.ts"

# Ask for clean code guidance
claude "review this file for code quality"

Writing Mode (automatic)