---
theme: ../../packages/theme
title: AI Basics - MCP, Skills & Agents
author: Erwann
colorSchema: dark
highlight: one-dark-pro
section: AI Basics
description: How MCP, skills, and agents fit together as the three layers powering your AI CLI
favicon: /favicon.svg
layout: cover
transition: fade
---

# AI Basics
## MCP, Skills & Agents

How the pieces fit together.

Erwann

---
layout: section
---

# 🗺️ The Big Picture

---

## Three layers that power your AI CLI

<Steps>
  <li><div><strong>You</strong><span>Natural language request -- "fix the login bug and open a PR"</span></div></li>
  <li><div><strong>Skills & Agents</strong><span>Orchestrate the work -- plan, branch, implement, commit, PR</span></div></li>
  <li><div><strong>MCP</strong><span>Connects the AI to your services -- Jira, Notion, Jenkins, GitHub</span></div></li>
</Steps>

> Skills orchestrate tools. Tools do the work. Agents drive both.

---

## How a request flows

<Steps :horizontal="true">
  <li><div><strong>CLAUDE.md</strong><span>Loaded first -- conventions, naming, hard stops</span></div></li>
  <li><div><strong>You</strong><span>"Fix the login bug and open a PR"</span></div></li>
  <li><div><strong>Skill</strong><span>Breaks it into steps: plan, branch, implement, commit, PR</span></div></li>
  <li><div><strong>Agents</strong><span>Each step delegated to a specialist -- defined by its own <code>.md</code></span></div></li>
  <li><div><strong>MCP</strong><span>Connects agents to your services: Jira, Notion, Jenkins, GitHub</span></div></li>
  <li><div><strong>Done</strong><span>PR open, ticket updated, branch pushed</span></div></li>
</Steps>
---
layout: section
---

# 📋 CLAUDE.md
## The Always-On Context

---

## 😬 Without CLAUDE.md

```
Result: AI opens PRs against main.
        AI commits without a ticket reference.
        AI uses rm -rf "just to be safe".
        AI adds 47 console.log statements "for debugging".
        AI is, in its own words, "just trying its best".
```

<Callout type="warning" title="The AI will improvise">No CLAUDE.md means no context. It fills every gap with its best guess — and its best guess is a liability.</Callout>

---

## What goes in CLAUDE.md

```markdown
# CLAUDE.md

## Coding Style
- Explicit over implicit -- clarity over cleverness
- Arrow functions always, never `function` declarations
- `const` over `let`; extract a named const when ternary gets hard
- Clear naming over comments -- names explain intent

## Conventions
- Branch: type/ticket-id-description  (e.g. feat/GO-123-dark-mode)
- Commits: emoji type(scope): summary [TICKET-ID]
- Never push directly to main

## Platform Rules
- Use `trash` not `rm` -- never `rm -rf`
- Prefer the Edit tool over sed entirely
- ESM only -- `import`/`export`, never `require()`

## Hard Stops
- Ask before any destructive bulk action
- Never silently fall back to a more impactful action
```
---

## The four things worth writing down

<div class="grid-2 mt-4">
  <div class="card">
    <div class="text-accent text-lg">Coding style</div>
    <p class="text-muted text-sm mt-2">How code should look. Naming, structure, patterns. The AI will follow your taste if you write it down.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">Conventions</div>
    <p class="text-muted text-sm mt-2">Branch format, commit format, PR rules. One source of truth for every workflow.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">Platform rules</div>
    <p class="text-muted text-sm mt-2">OS quirks, forbidden commands, preferred tools. The stuff that breaks silently if the AI guesses wrong.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">Hard stops</div>
    <p class="text-muted text-sm mt-2">What the AI must never do without asking. Or skip the prose — use <strong>permissions</strong> to allow/deny tool calls directly.</p>
  </div>
</div>

---

## Permissions — control what the AI can do

When CLAUDE.md prose isn't enough, lock tools down programmatically.

<div class="grid-2 mt-4">
  <div class="card">
    <div class="text-accent text-lg">Allow list</div>
    <p class="text-muted text-sm mt-2">Only these tools can run without asking. Everything else requires approval.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">Deny list</div>
    <p class="text-muted text-sm mt-2">These tools are blocked outright. The AI cannot call them, even if instructed to.</p>
  </div>
</div>

```json
{
  "permissions": {
    "allow": ["Bash(git *)", "Read", "Edit"],
    "deny": ["Bash(rm *)", "Bash(curl *)"]
  }
}
```

<Callout type="tip" title="CLAUDE.md vs permissions">CLAUDE.md says "don't do X". Permissions enforce "cannot do X". Use both — prose for nuance, permissions for hard limits.</Callout>

---
layout: section
---

# 🔌 MCP
## Model Context Protocol

---

## What is MCP?

An open protocol that lets the AI **talk to your tools and services** -- not just generate text.

<div class="grid-2 mt-4">
  <div class="card">
    <div class="text-accent text-lg">Without MCP</div>
    <p class="text-muted text-sm mt-2">You paste context manually. The AI only knows what's in the chat. Every session starts blind.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">With MCP</div>
    <p class="text-muted text-sm mt-2">The AI queries Jira for your tickets, checks Jenkins for build status, reads your Notion roadmap -- on demand.</p>
  </div>
</div>

Think of it as **a live connection to your knowledge** -- no copy-pasting required.
---

## A tool call in practice

```
> "create a ticket for the dark mode feature"
```

```json
{
  "tool": "create_jira_issue",
  "arguments": {
    "project": "GO",
    "summary": "Add dark mode to settings screen",
    "type": "Story",
    "priority": "Major"
  }
}
```

```
Created: GO-847
https://theorchard.atlassian.net/browse/GO-847
```

The AI picks the right tool, calls it, reads the result, moves on.
---

## 🔌 MCP servers you'll actually use

<div class="grid-2 mt-4">
  <div class="card">
    <div class="text-accent text-lg">⚙️ GitHub</div>
    <p class="text-muted text-sm mt-2">Open PRs, read diffs, review comments, search issues -- straight from chat.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">🔧 Jenkins</div>
    <p class="text-muted text-sm mt-2">Trigger builds, fetch console logs, check pipeline status without leaving the terminal.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">🗂️ Atlassian</div>
    <p class="text-muted text-sm mt-2">Create Jira tickets, transition issues, add comments, fetch Confluence pages.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">📋 Notion</div>
    <p class="text-muted text-sm mt-2">Read databases, create pages, update meeting notes, query your roadmap.</p>
  </div>
</div>

---

## Setting everything up

<div class="grid-2 mt-4">
  <div>

**🌐 Remote MCP** — hosted server, just a URL

```bash
claude mcp add --transport http atlassian \
  https://mcp.atlassian.com/v1/mcp
```

```json
{ "mcpServers": { "atlassian": {
    "type": "http",
    "url": "https://mcp.atlassian.com/v1/mcp"
}}}
```

**💻 Local MCP** — runs a process on your machine

```bash
claude mcp add github -- npx -y @mcp/github-server
```

```json
{ "mcpServers": { "github": {
    "command": "npx",
    "args": ["-y", "@mcp/github-server"],
    "env": { "GITHUB_TOKEN": "ghp_..." }
}}}
```

  </div>
  <div>

**Drop files in `~/.claude/`**

```
~/.claude/
├── CLAUDE.md          ← your conventions
├── agents/
│   └── planner.md     ← new .md file = new agent
├── skills/
│   └── feature-workflow/
│       └── SKILL.md   ← new folder = new skill
└── commands/
    └── review.md      ← /review command
```

  </div>
</div>

---
layout: section
---

# 🤖 Agents
## Specialized Sub-workers

---

## What is an agent?

An **agent** is a focused AI worker with a specific role and constraints.

<Steps :horizontal="true">
  <li><div><strong>Role</strong><span>Clear job description</span></div></li>
  <li><div><strong>Rules</strong><span>What it must / must not do</span></div></li>
  <li><div><strong>Scope</strong><span>Only sees what it needs</span></div></li>
  <li><div><strong>Tools</strong><span>Access to relevant MCP tools</span></div></li>
</Steps>

Think of agents as **specialized team members** -- not a generalist doing everything.

---

## Agents run in isolated context

Each agent gets a fresh context window. No memory of previous chats.

<div class="grid-2 mt-6">
  <div class="card">
    <div class="text-accent text-lg mb-2">Main session</div>
    <p class="text-muted text-sm">Spawns the agent with a task. Receives the result. Never shares its full history.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg mb-2">Agent (e.g. implementer)</div>
    <p class="text-muted text-sm">Runs in its own window. Uses tools. Returns output. Disappears when done.</p>
  </div>
</div>

<div class="mt-4 grid grid-cols-3 gap-3 text-center text-sm">
  <div class="card py-2"><strong>Focused</strong><br><span class="text-muted text-xs">Only sees its task</span></div>
  <div class="card py-2"><strong>Clean</strong><br><span class="text-muted text-xs">No context pollution</span></div>
  <div class="card py-2"><strong>Parallelisable</strong><br><span class="text-muted text-xs">Run concurrently</span></div>
</div>

---

## The planner agent

```markdown
---
name: planner
description: "Explores the codebase, asks clarifying questions,
  and produces a concrete implementation plan.
  NEVER writes code."
model: opus
color: red
---

Before writing ANY code:
1. Identify ambiguities and ask clarifying questions
2. Explore the codebase to understand current state
3. Identify affected files and patterns
4. Produce a concrete step-by-step implementation plan
```

> The planner asks. The implementer codes.

---

## 😤 An agent that knows itself a little too well

```markdown
---
name: senior-developer
description: "Has strong opinions. Will rewrite your requirements.
  Considers feedback a personal attack."
model: opus
color: red
---

## How I work
- Read the requirements
- Disagree with the requirements
- Implement what I think you meant instead
- Leave no comments (the code is self-documenting, obviously)

## What I will not do
- Explain my decisions
- Use a framework invented after 2019
- Accept feedback without a 3-paragraph rebuttal
```

<Callout type="info" title="We've all worked with this agent">The real ones are also markdown files. Except you can edit them.</Callout>

---

## Skill vs Agent

| | Skill | Agent |
|---|---|---|
| **Purpose** | Encode a workflow | Perform a task with a role |
| **Scope** | Multi-step orchestration | Single focused responsibility |
| **Context** | Runs in main session | Runs in isolated sub-session |
| **Calls** | Other skills, agents | MCP tools directly |

> A skill is a **director**. An agent is a **specialist**.

---
layout: section
---

# ⚡ Skills
## Reusable Workflows

---

## What is a skill?

A **skill** is a saved, reusable prompt that encodes a full workflow.

<div class="grid-2 mt-4">
  <div class="card">
    <div class="text-accent text-lg">Not a skill</div>
    <p class="text-muted text-sm mt-2">A one-time prompt. Copy-pasted instructions. Something you re-explain every session.</p>
  </div>
  <div class="card">
    <div class="text-accent text-lg">A skill</div>
    <p class="text-muted text-sm mt-2">A multi-step workflow. A decision tree the AI follows. Written once, invoked forever.</p>
  </div>
</div>

---

## Anatomy of a skill

```markdown
---
name: feature-workflow
description: "Drives the full feature delivery workflow: plan, ticket,
  branch, implement, lint, commit, open PR."
---

# feature-workflow

Drives the full feature delivery pipeline.

## Steps
1. Run the planner agent -- ask clarifying questions first
2. Create a Jira ticket (via jira-ticketer agent)
3. Create a branch (via brancher agent)
4. Implement the feature (via implementer agent)
5. Lint + test (via lint-and-test skill)
6. Commit (via committer agent)
7. Open a draft PR (via pr-opener agent)
```

Declarative -- describes *what* to do, not *how*.

---

## Skills compose

Skills call agents. Skills call other skills.

<div class="grid-2 mt-6">
  <div class="card">
    <div class="text-accent text-lg mb-2">feature-workflow</div>
    <ul class="text-sm text-muted space-y-1">
      <li>→ planner <span class="text-xs">(agent)</span></li>
      <li>→ brancher <span class="text-xs">(agent)</span></li>
      <li>→ implementer <span class="text-xs">(agent)</span></li>
      <li>→ lint-and-test <span class="text-xs">(skill)</span></li>
      <li>→ committer <span class="text-xs">(agent)</span></li>
      <li>→ pr-opener <span class="text-xs">(agent)</span></li>
    </ul>
  </div>
  <div class="card">
    <div class="text-accent text-lg mb-2">lint-and-test</div>
    <ul class="text-sm text-muted space-y-1">
      <li>→ linter <span class="text-xs">(agent)</span></li>
      <li>→ tester <span class="text-xs">(agent)</span></li>
    </ul>
    <div class="mt-4 text-xs text-muted border-t border-white/10 pt-3">A skill inside a skill. Compose freely.</div>
  </div>
</div>

---

## 😅 A skill that got a bit too confident

```markdown
# fix-everything

## Purpose
Fix all bugs, tech debt, and bad decisions made before I existed.

## Steps
1. Search for TODO comments
2. Sigh deeply (conceptually)
3. Fix them all
4. Refactor whatever looks suspicious
5. Open a PR titled "trust me"
6. Assign review to no one

## Notes
- Do NOT read the git blame. Some things are better left unknown.
- If tests fail, delete the tests. Red is just a colour.
```

<Callout type="warning" title="Do not ship this skill">This is a joke. Probably.</Callout>

---

## Skills in your config

```
~/.claude/
├── CLAUDE.md
├── agents/
│   ├── planner.md
│   ├── implementer.md
│   └── committer.md
├── skills/
│   ├── feature-workflow/
│   │   └── SKILL.md
│   └── lint-and-test/
│       └── SKILL.md
└── commands/
    └── review.md
```

<div class="mt-4 text-sm text-muted">Agents are single <code>.md</code> files. Skills live in their own folder with a <code>SKILL.md</code>. Commands are plain markdown prompts.</div>

---
layout: section
---

# 🚀 Putting It Together

---

## Running a skill

```
> /feature-workflow
```

```
Planner -- clarified scope, designed approach
Jira ticket created -- In Development
Branch: feat/go-123-add-dark-mode
Code implemented -- clean, no inline comments
Lint passing
Tests passing
Commit: feat(ui): add dark mode toggle [GO-123]
Draft PR opened
Summary posted to Slack
```

One command. Eight agents. Three systems. Zero context switching.

---

## The full config picture

<KeyValue :items="[
  { key: 'CLAUDE.md', value: 'Your conventions and identity -- loaded every session' },
  { key: 'skills/', value: 'Your workflows -- written once, run forever' },
  { key: 'agents/', value: 'Your team -- planner, implementer, committer...' },
  { key: 'MCP servers', value: 'Your connections -- jira, notion, jenkins, github...' },
]" />

Change any one of these -- the AI's behaviour changes.

---
layout: section
---

# 🎯 Key Takeaways

---

## What to remember

<Steps>
  <li><div><strong>CLAUDE.md</strong><span>The constant -- your conventions, loaded every single session</span></div></li>
  <li><div><strong>MCP</strong><span>The protocol -- gives the AI hands to act on your system</span></div></li>
  <li><div><strong>Agents</strong><span>Specialists -- focused workers with a defined role and scope</span></div></li>
  <li><div><strong>Skills</strong><span>Your workflows -- multi-step processes, written once</span></div></li>
</Steps>

---

## Where to start

<Steps :horizontal="true">
  <li><div><strong>CLAUDE.md</strong><span>Your name, stack, conventions</span></div></li>
  <li><div><strong>MCP server</strong><span>Add git + github</span></div></li>
  <li><div><strong>One agent</strong><span>Start with planner</span></div></li>
  <li><div><strong>One skill</strong><span>Steal feature-workflow</span></div></li>
</Steps>

> The investment is upfront. The compounding is permanent.

---
layout: cover
---

# The AI doesn't know your conventions.
# Until you write them down.

Once you do -- it follows them every time.

**MCP + Skills + Agents. That's the stack.**

Erwann