ysskrishna logoysskrishna

Chapter 1 of 9 · 4 min

The four building blocks, and when to reach for each

Skills teach, subagents delegate, MCP servers connect, hooks enforce. A one-page mental model you will use for the rest of the course.

Every serious agent setup ends up using the same four parts. Cursor and Claude Code name them slightly differently, and the docs cover them in separate pages, so it is easy to miss how they fit. This chapter gives you the map. The next eight chapters build each part for real.

The problem each one solves

Start with what goes wrong when you only have a chat box and a model:

  1. You repeat yourself. Every session you paste the same "here is how we write migrations" paragraph. The agent forgets it next time.
  2. One context does everything. A big search through the repo fills the context window with file listings, and the model gets worse at the actual change you asked for.
  3. The agent can't reach your systems. It can edit files and run shell commands, but it can't read a Jira ticket or post a correctly formatted Slack message without you copying things around.
  4. Rules are suggestions. You can write "never run rm -rf" in a prompt. The model will usually obey. "Usually" is not a guarantee.

Each building block fixes one of those.

ProblemBuilding blockWhat it is, physically
Repeating instructionsSkillA folder with a SKILL.md (and optional scripts or references) that the agent loads when the task matches its description
One overloaded contextSubagentA Markdown file describing a helper agent with its own instructions, tool list and model; it works in a separate context and hands back a result
No access to your systemsMCP serverA program that speaks the Model Context Protocol and exposes tools, resources and prompts to any MCP host
Rules that must holdHookA command the host runs on an event (before a tool call, after an edit, when the agent stops) whose exit code can block the action

A quick way to choose

Ask three questions, in this order:

  1. Does this need to happen every time, no matter what the model thinks? Use a hook. Formatting after every edit, blocking writes to .env, refusing git push --force on main.
  2. Does the agent need to reach something outside the repo and shell? Use an MCP server. A ticket tracker, a database, a converter for Slack or Jira formatting.
  3. Is it knowledge or a method the agent should apply? Use a skill. "How we review PRs", "run a pre-mortem", "write release notes in our format".

Then a fourth question for big jobs:

  1. Would the work flood the main conversation, or does it suit a cheaper model? Wrap it in a subagent. Searching a large codebase, proofreading, summarising logs.

Two of these are about knowledge (skills, subagents) and two are about plumbing (MCP, hooks). Mixing them up is the most common design mistake: people write a skill that says "always run the formatter", which is a hook's job, or build an MCP server for what is really a checklist, which is a skill's job.

How they look on disk

In a project that uses all four, you would see something like this:

my-repo/
├── .claude/
│   ├── agents/
│   │   └── scout.md              # subagent: read-only repo explorer
│   ├── skills/
│   │   └── release-notes/
│   │       └── SKILL.md          # skill: how we write release notes
│   └── settings.json             # hooks live here in Claude Code
├── .cursor/
│   ├── agents/                   # Cursor also reads .claude/agents
│   ├── mcp.json                  # MCP servers for this project
│   └── hooks.json                # Cursor hooks
└── src/ ...

User-level versions of the same folders (~/.claude/…, ~/.cursor/…, ~/.agents/skills/…) apply to every project. Project-level files win when both exist, and they are the ones you commit so your team gets the same behaviour.

One example, four parts

Say you want the agent to "write the weekly release notes and post them to the team channel".

  • A skill called release-notes holds the format: sections, tone, how to group PRs, what to leave out.
  • A subagent called changelog-scout runs on a small model, reads the merged PRs and returns a short list. Your main chat never sees the hundred PR bodies.
  • An MCP server such as Markdown Convert MCP turns the Markdown draft into Slack mrkdwn before your Slack tool sends it.
  • A hook blocks the Slack send tool unless a human-approved flag file exists, so a draft never goes out by accident.

Remove any one of those and the workflow still runs, but it gets more expensive, less consistent or less safe. That is the test for whether a building block earns its place.

What this course does not cover

Model choice, fine-tuning, and writing your own agent framework from scratch. Everything here works with the hosts you already use. Where Cursor and Claude Code differ, the chapter says so. Check the current docs before relying on a path or file name that hosts change often.

Quick check

  1. You want every edited Python file formatted with ruff, always. Which building block?A hook (an after-edit / PostToolUse hook that runs ruff format). A skill could ask for it, but only a hook guarantees it.

  2. Your team has a 40-line checklist for reviewing database migrations. Which building block?A skill. It is a method the agent should apply when the task is a migration review.

  3. The agent needs to read issues from your tracker. Which building block?An MCP server for the tracker (many trackers publish one), connected in your host's MCP config.

  4. A codebase search returns thousands of lines and drowns the conversation. What helps?A subagent: it searches in its own context, on a cheaper model if you like, and returns only the summary.

Continue exploring

Productnpm+3Thinking Methods

Thinking Methods

17 well-known thinking methods your AI coding assistant can actually run.
Agent Skills
AI Apps & Assistants
Bash
Gemini
BlogCover image for 17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

AI Apps & Assistants
Agent Skills
4 min read
ToolCover image for AI Token Counter

AI Token Counter

AI token counter with model pricing and context-window comparison in your browser.

Chat & AI
AI Apps & Assistants
+1
Productskills.sh+1Claude Code Subagents for Cursor

Claude Code Subagents for Cursor

Your Cursor subagents can finally run on the model you picked in each agent file.
Chat & AI
Agent Skills
AI Apps & Assistants
Bash
CourseCover image for Prompt Engineering for Coding Agents

Prompt Engineering for Coding Agents

Write prompts that coding agents act on: clear goals, the right context, output contracts, examples, structured thinking, shorter answers and a tiny eval set.

Agent Skills
Chat & AI

8 chapters · 21 min

BlogCover image for How to Install Caveman in Cursor and Claude Code

How to Install Caveman in Cursor and Claude Code

AI Apps & Assistants
Agent Skills
+1
3 min read