AI Coding Tutorial: Skills, MCP & Project Conventions

Level up from "chatting with an AI" to "running a well-organized AI engineering workflow"

🎯 Why this section exists

Claude Code (and similar tools like Codex, Gemini CLI) become dramatically more effective once a project defines how the AI should work with the codebase — not just what to build. This tutorial covers the four building blocks that make that possible:

Building block	What it solves	Read next
Skills	Package repeatable expertise (coding standards, workflows, checklists) that the AI loads only when relevant	Claude Skills
MCP	Connect the AI to live external systems — databases, APIs, internal tools — via a standard protocol	MCP (Model Context Protocol)
AGENTS.md	A single onboarding doc so any AI agent understands your architecture, build commands, and conventions	AGENTS.md for Enterprise Projects
.claude config layers	Global vs. project vs. local configuration — who owns each layer and what belongs where	.claude Configuration Layers

💡 Who this is for

Individual developers who want a cleaner personal setup, and teams who want every engineer's AI assistant to follow the same architecture, conventions, and guardrails — without repeating instructions in every conversation.

🧩 The mental model

Think of an AI coding agent's "knowledge" as layered, from broadest to narrowest:

~/.claude/                     Global — applies to every project on your machine
  ├── CLAUDE.md                 personal defaults, coding style preferences
  ├── settings.json             global permissions, hooks, env vars
  └── skills/                   personal skills available everywhere

<project>/AGENTS.md             Project — cross-tool onboarding doc (Claude Code, Codex, Cursor…)
<project>/CLAUDE.md              Project — Claude Code specific entry point
<project>/.claude/
  ├── settings.json              team-shared config, committed to git
  ├── settings.local.json        personal overrides, NOT committed (gitignored)
  ├── rules/*.md                 path-scoped conventions, auto-loaded by file path
  └── skills/<name>/SKILL.md     on-demand expertise, loaded only when triggered

The further down this tree a file lives, the more specific and higher-priority it is. A well-run enterprise repo uses all four layers together: AGENTS.md for onboarding, rules for automatic path-based conventions, skills for on-demand deep expertise, and settings.local.json for individual permission tweaks.

🚀 Suggested reading order

1. Start with AGENTS.md — it's the front door of your repo for any AI agent.
2. Then .claude Configuration Layers — understand global vs. project vs. local, and what rules/ vs skills/ are for.
3. Then Claude Skills — learn to package reusable expertise properly.
4. Finish with MCP — connect your AI to real systems (databases, issue trackers, internal APIs).

🎉 Goal

By the end of this section you'll be able to set up a repository so that any teammate's Claude Code session — or even a different tool like Codex — starts with the same architectural understanding, the same coding conventions, and the same safe permission boundaries.