Code Craft

Discipline-enforcing skills that help AI coding agents write better code by following software engineering best practices.

What Are These?

Skills are documents that teach Claude to resist common bad patterns and produce higher quality code. Unlike tutorials, these skills:

Resist pressure - Handle "just make it work" or "don't overcomplicate" requests
Close loopholes - Address specific rationalizations Claude uses to violate principles
Provide correct patterns - Show the right way, not just explain what's wrong

Each skill was developed using TDD for documentation: baseline tests reveal how Claude fails without the skill, then the skill is written to address those specific failures.

Installation

npx add-skill yanko-belov/code-craft

This installs skills to all supported agents (OpenCode, Claude Code, Codex, Cursor, etc.)

Options

# Install specific skills only
npx add-skill yanko-belov/code-craft -s single-responsibility yagni fail-fast

# Install globally (user-level)
npx add-skill yanko-belov/code-craft -g

# Install to specific agents
npx add-skill yanko-belov/code-craft -a opencode claude-code

# List available skills
npx add-skill yanko-belov/code-craft -l

# Install all skills to all agents without prompts
npx add-skill yanko-belov/code-craft --all

Supported Agents

OpenCode
Claude Code
Codex
Cursor
Antigravity
GitHub Copilot
Roo Code

Manual Installation

# Clone and symlink
git clone https://github.com/yanko-belov/code-craft.git
cd code-craft
for skill in skills/*/; do
  ln -sf "$(pwd)/$skill" ~/.claude/skills/
done

Skills

SOLID Principles

| Principle | Skill | Prevents | |-----------|-------|----------| | S | Single Responsibility | God classes, "just add it here" | | O | Open/Closed | Adding if/else branches for new features | | L | Liskov Substitution | Override with throw/no-op | | I | Interface Segregation | Fat interfaces, forced implementations | | D | Dependency Inversion | new Concrete() inside classes |

Core Principles

| Principle | Skill | Prevents | |-----------|-------|----------| | DRY | Don't Repeat Yourself | Copy-paste code, duplicated logic | | YAGNI | You Ain't Gonna Need It | Over-engineering, speculative features | | KISS | Keep It Simple | Clever one-liners, unnecessary complexity | | Composition | Composition over Inheritance | Deep inheritance hierarchies | | Demeter | Law of Demeter | a.b.c.d property chains | | Fail Fast | Fail Fast | Swallowed errors, silent failures |

Testing

| Skill | Prevents | |-------|----------| | TDD | Tests as afterthought, untestable code | | Test Isolation | Flaky tests, shared state between tests | | AAA Pattern | Messy tests, unclear test structure |

Security

| Skill | Prevents | |-------|----------| | Input Validation | Injection attacks, invalid data | | Secrets Handling | Hardcoded credentials, exposed secrets | | Auth Patterns | Broken authentication, insecure sessions |

API Design

| Skill | Prevents | |-------|----------| | REST Conventions | Inconsistent endpoints, poor API design | | Error Responses | Unhelpful errors, leaked internals | | Idempotency | Duplicate operations, unsafe retries | | API Versioning | Breaking changes, version chaos |

Performance

| Skill | Prevents | |-------|----------| | N+1 Prevention | Database query explosions | | Lazy Loading | Loading everything upfront, slow startup | | Caching | Repeated expensive operations, cache bugs |

Code Quality

| Skill | Prevents | |-------|----------| | Separation of Concerns | Mixed responsibilities, tangled code | | Encapsulation | Exposed internals, broken abstractions | | Immutability | Mutation bugs, unexpected state changes |

Error Handling

| Skill | Prevents | |-------|----------| | Exception Hierarchies | Generic errors, poor error handling | | Error Boundaries | Cascading failures, crashed UIs |

Concurrency

| Skill | Prevents | |-------|----------| | Race Conditions | Data races, inconsistent state | | Deadlock Prevention | System hangs, resource starvation |

How Skills Work

Each skill follows a consistent structure:

| Section | Purpose | |---------|---------| | Iron Rule | The non-negotiable principle | | Detection | How to recognize violations | | Correct Pattern | Code examples of the right way | | Pressure Resistance | Handling pushback scenarios | | Red Flags | Warning signs to watch for | | Rationalizations | Common excuses and rebuttals |

Example: YAGNI in Action

Without skill:

User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates 500-line "production-ready" system with pagination,
        rate limiting, soft delete, health checks, audit logs...*

With YAGNI skill:

User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates exactly 3 endpoints in 30 lines*
        "Add pagination when the list grows. Add rate limiting if 
        there's abuse. Don't pay for features you don't need yet."

Skill Categories

| Category | Skills | Focus | |----------|--------|-------| | SOLID | 5 | Object-oriented design principles | | Core | 6 | Fundamental coding principles | | Testing | 3 | Test quality and structure | | Security | 3 | Secure coding practices | | API Design | 4 | RESTful API best practices | | Performance | 3 | Optimization patterns | | Code Quality | 3 | Clean code patterns | | Error Handling | 2 | Exception management | | Concurrency | 2 | Thread-safe patterns | | Meta | 1 | Skill usage tracking |

Total: 32 skills

Contributing

Adding a New Skill

Baseline test - Run pressure scenarios without the skill
Document failures - Record exactly how Claude violates the principle
Write skill - Address those specific failures with Iron Rule + Pressure Resistance
Test with skill - Verify Claude now complies under the same pressure
Refactor - Close any loopholes found

Skill Template

---
name: principle-name
description: Use when [specific triggering conditions]
---

# Principle Name

## Overview
[Core principle in 1-2 sentences]

## The Iron Rule
[Non-negotiable statement]

## Detection
[How to spot violations]

## Correct Pattern
[Code examples]

## Pressure Resistance Protocol
[Handling pushback]

## Red Flags
[Warning signs]

## Common Rationalizations
[Excuses + rebuttals table]

License

MIT

code-craft

💡 摘要

🎯 适合人群