I Taught Claude Code My Company Codebase. Here is What Happened

Last week, I spent 45 minutes explaining our API conventions to a new junior developer. It hit me: I have done this conversation dozens of times. What if I could teach Claude Code once and have it remember?

So I built our first custom skill. Three days later, it knows our error handling patterns, our naming conventions, and when to push back on my bad ideas.

Here is how you can do the same - and why it changes everything about working with AI coding assistants.

The Problem With Generalist AI

Here is the thing about Claude Code (and Cursor, and Copilot): they are brilliant at writing code. But they do not know your code.

When I ask Claude to add authentication to this endpoint, it does not know:

• We use a specific middleware pattern, not decorators
• Our error responses follow a strict JSON schema
• We never expose stack traces in production

AI coding assistants do not know your code. They do not know your conventions, your patterns, or your team preferences.

— The Real Issue

You end up repeating yourself. Remember, we use async handlers that return Either Success or Error becomes a mantra you say to every new session.

That is where skills come in.

What Skills Actually Do

Think of skills as giving Claude Code a cheat sheet for your project. Not the whole codebase - just the parts that matter for specific tasks.

When you install the Claude Skills plugin marketplace, you get 66 pre-built skills. But the magic is not in those skills - it is in understanding how they work:

Build a React component with Server Components
-> Activates: React Expert -> Loads: references/server-components.md

See what happened? The skill:

1. Detected context (you want to build something with React)
2. Activated a specialty (React Expert)
3. Loaded relevant docs (server components reference)

That is it. You can build the same system for your project.

Building Your First Skill (In 15 Minutes)

Let me walk you through building a skill for our API error handling. This is something we do constantly, and explaining it every time was killing me.

Step 1: Create the skills directory

mkdir -p ~/.claude/skills/my-company
mkdir -p ~/.claude/skills/my-company/references

Step 2: Write the skill definition

Create ~/.claude/skills/my-company/skill.md:

# API Error Handling

You apply our API error handling conventions to all new endpoints.

When implementing error handling:
- Use our middleware pattern: withErrorHandler(async (req, res) => {...})
- All errors return { code: string, message: string, details?: object }
- Never expose internal error codes to clients
- Log full error with correlation ID for debugging

Step 3: Add a reference file

Create ~/.claude/skills/my-company/references/error-handling.md:

// Response Schema
interface ApiError {
  code: string;
  message: string;
  details?: Record<string, any>;
}

// Middleware Pattern
import { withErrorHandler } from '../middleware/error';

router.get('/users/:id', withErrorHandler(async (req, res) => {
  const user = await getUser(req.params.id);
  if (!user) {
    throw new NotFoundError('User not found');
  }
  res.json(user);
}));

Step 4: Register the skill

Add to your claude_settings.json:

{
  "skills": {
    "api-errors": {
      "path": "~/.claude/skills/my-company"
    }
  }
}

Now when you say add error handling to this route, Claude loads your conventions automatically.

The Context Engineering Secret

Here is what most people miss: skills work best when they surface assumptions.

The documentation mentions /common-ground - a command that validates Claude hidden assumptions about your project. This is huge.

The real power is not in telling Claude what to do. It is in discovering what it already assumes - and correcting those assumptions before they cause bugs.

— The Game Changer

When you run /common-ground, Claude lists what it thinks your project looks like. Things like:

• Uses TypeScript for type safety
• Follows React functional component patterns
• Uses Express for the API

Some of these are right. Some are wrong. And until you check, you are flying blind.

My Common Ground Results (Surprising)

I ran this on our main project expecting clean results. Instead:

Correct: Uses TypeScript Correct: REST API with Express Wrong: Uses Prisma for database (we switched to Drizzle) Wrong: React 18 with hooks (we are on React 19)

That is when I realized: Claude had been generating Prisma code. For eight months. In a codebase that has not used Prisma in two years.

Skills That Actually Made a Difference

After two weeks of building skills, here are the ones that stuck:

1. Our Testing Patterns

Not just use Jest. Our specific patterns:

• Mock external APIs with msw
• Use describe/given/when/then structure
• One assertion per test

2. Our Git Commit Conventions

• Conventional commits with specific types
• PRs need 2 approvals
• Squash merge only

3. Our Code Review Triggers

• Security: always require second pair of eyes
• Database migrations: always involve our DBA
• API changes: always include contract tests

When Skills Do Not Work

Let us be honest - not every skill is worth it:

• Do not create skills for one-off tasks
• Do not create skills for well-documented things
• Do not create skills you will not use
• Do not over-engineer skills

The Workflow Command Revolution

The skills system also includes workflow commands - pre-built sequences that handle complex multi-step tasks.

Want to implement a feature? There is a workflow for that:

1. Feature Forge - Creates the initial implementation
2. Architecture Designer - Reviews the design
3. Fullstack Guardian - Checks for issues
4. Test Master - Generates tests
5. DevOps Engineer - Handles deployment

The skill system is not about replacing your judgment. It is about encoding your expertise so you do not have to repeat it.

— The Future

Your Turn

If you are using Claude Code (or any AI coding assistant), here is your homework:

1. Install the skills plugin: /plugin marketplace add jeffallan/claude-skills
2. Run /common-ground on your main project
3. Fix one wrong assumption
4. Build one skill for your most common task

It took me about an hour to get started. The first skill took another hour to refine. Now I have five that I use daily.

That is three hours invested. I have already gotten that time back in reduced explanations and more consistent code.

Skills are not about making Claude smarter. They are about making your expertise reusable. And that changes how you work with AI.

— The Bottom Line

The future of AI coding is not about more powerful models. It is about teaching them your context. Skills are how you do that.