---
slug: "code-craft"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/yanko-belov/code-craft@master/README.md"
repo: "https://github.com/yanko-belov/code-craft"
source_file: "README.md"
branch: "master"
---
# 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

```bash
npx add-skill yanko-belov/code-craft
```

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

### Options

```bash
# 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

```bash
# 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](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/single-responsibility/SKILL.md) | God classes, "just add it here" |
| **O** | [Open/Closed](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/open-closed/SKILL.md) | Adding if/else branches for new features |
| **L** | [Liskov Substitution](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/liskov-substitution/SKILL.md) | Override with throw/no-op |
| **I** | [Interface Segregation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/interface-segregation/SKILL.md) | Fat interfaces, forced implementations |
| **D** | [Dependency Inversion](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/dependency-inversion/SKILL.md) | `new Concrete()` inside classes |

### Core Principles

| Principle | Skill | Prevents |
|-----------|-------|----------|
| **DRY** | [Don't Repeat Yourself](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/dry/SKILL.md) | Copy-paste code, duplicated logic |
| **YAGNI** | [You Ain't Gonna Need It](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/yagni/SKILL.md) | Over-engineering, speculative features |
| **KISS** | [Keep It Simple](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/kiss/SKILL.md) | Clever one-liners, unnecessary complexity |
| **Composition** | [Composition over Inheritance](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/composition-over-inheritance/SKILL.md) | Deep inheritance hierarchies |
| **Demeter** | [Law of Demeter](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/law-of-demeter/SKILL.md) | `a.b.c.d` property chains |
| **Fail Fast** | [Fail Fast](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/fail-fast/SKILL.md) | Swallowed errors, silent failures |

### Testing

| Skill | Prevents |
|-------|----------|
| [TDD](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/tdd/SKILL.md) | Tests as afterthought, untestable code |
| [Test Isolation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/test-isolation/SKILL.md) | Flaky tests, shared state between tests |
| [AAA Pattern](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/aaa-pattern/SKILL.md) | Messy tests, unclear test structure |

### Security

| Skill | Prevents |
|-------|----------|
| [Input Validation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/input-validation/SKILL.md) | Injection attacks, invalid data |
| [Secrets Handling](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/secrets-handling/SKILL.md) | Hardcoded credentials, exposed secrets |
| [Auth Patterns](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/auth-patterns/SKILL.md) | Broken authentication, insecure sessions |

### API Design

| Skill | Prevents |
|-------|----------|
| [REST Conventions](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/rest-conventions/SKILL.md) | Inconsistent endpoints, poor API design |
| [Error Responses](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/error-responses/SKILL.md) | Unhelpful errors, leaked internals |
| [Idempotency](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/idempotency/SKILL.md) | Duplicate operations, unsafe retries |
| [API Versioning](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/api-versioning/SKILL.md) | Breaking changes, version chaos |

### Performance

| Skill | Prevents |
|-------|----------|
| [N+1 Prevention](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/n-plus-one-prevention/SKILL.md) | Database query explosions |
| [Lazy Loading](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/lazy-loading/SKILL.md) | Loading everything upfront, slow startup |
| [Caching](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/caching/SKILL.md) | Repeated expensive operations, cache bugs |

### Code Quality

| Skill | Prevents |
|-------|----------|
| [Separation of Concerns](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/separation-of-concerns/SKILL.md) | Mixed responsibilities, tangled code |
| [Encapsulation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/encapsulation/SKILL.md) | Exposed internals, broken abstractions |
| [Immutability](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/immutability/SKILL.md) | Mutation bugs, unexpected state changes |

### Error Handling

| Skill | Prevents |
|-------|----------|
| [Exception Hierarchies](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/exception-hierarchies/SKILL.md) | Generic errors, poor error handling |
| [Error Boundaries](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/error-boundaries/SKILL.md) | Cascading failures, crashed UIs |

### Concurrency

| Skill | Prevents |
|-------|----------|
| [Race Conditions](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/race-conditions/SKILL.md) | Data races, inconsistent state |
| [Deadlock Prevention](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/deadlock-prevention/SKILL.md) | System hangs, resource starvation |

### Meta

| Skill | Purpose |
|-------|---------|
| [Skill Awareness](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/skill-awareness/SKILL.md) | Tracks skill usage across sessions, enables analytics |

## 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

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

### Skill Template

```markdown
---
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