LAB: Path Instructions, Agents, and Skills

This lab has three parts. Each one takes about five to seven minutes. By the time you finish, you'll have a working setup with layered instructions, a custom subagent, and a skill you metaprompted Claude into writing for you.

No starter project required. You're building this from scratch.

Part 1: Path-Based Instructions (5-7 min)

Claude Code reads CLAUDE.md files the same way Node reads package.json, starting from where you're working and climbing the tree until it can't go further. Every file it finds along the way gets loaded. That's the whole mechanic, and it's more useful than it sounds.

Here's what we're going to prove.

Set up a simple project structure:

<span class="hljs-built_in">mkdir</span> my-project &amp;&amp; <span class="hljs-built_in">cd</span> my-project
<span class="hljs-built_in">mkdir</span> api frontend

Write a root CLAUDE.md:

<span class="hljs-built_in">cat</span> &gt; CLAUDE.md &lt;&lt; <span class="hljs-string">&#x27;EOF&#x27;</span>
<span class="hljs-comment"># Project Context</span>

This is a full-stack app. The API is Node/Express. The frontend is React.

<span class="hljs-comment">## Conventions</span>
- Use async/await everywhere (no .<span class="hljs-keyword">then</span>())
- All errors go through the error handler <span class="hljs-keyword">in</span> api/middleware/error.js
- Imports are always named, never default
EOF

Write an API-specific CLAUDE.md:

<span class="hljs-built_in">cat</span> &gt; api/CLAUDE.md &lt;&lt; <span class="hljs-string">&#x27;EOF&#x27;</span>
<span class="hljs-comment"># API Context</span>

This layer handles auth, data fetching, and validation.

<span class="hljs-comment">## API Rules</span>
- Every route needs input validation before it touches the database
- Use the ApiError class <span class="hljs-keyword">for</span> all thrown errors (not plain Error)
- Routes live <span class="hljs-keyword">in</span> api/routes/, controllers <span class="hljs-keyword">in</span> api/controllers/
EOF

Now ask Claude to confirm what it's loaded. Open Claude Code from the api/ directory (or cd api and launch) and ask:

"What CLAUDE.md files have you loaded for this session, and what do they say?"

It should list both -- the root and the api-specific one. Now go back to the root and open a file in frontend/. Ask the same question. This time you'll only see the root CLAUDE.md. The api context doesn't follow you.

That's path-based scoping. You write instructions once, and they show up exactly where they're relevant.

Here's how Claude Code's memory hierarchy works across the full stack:

The path-based experiment you just ran proves the last row: api/CLAUDE.md only loaded when Claude was in (or reading from) the api/ directory.

The practical use: put your testing framework in a /tests/CLAUDE.md. Put your database conventions in /db/CLAUDE.md. Put your deployment process in /infra/CLAUDE.md. Each one only loads when Claude is working in that part of the codebase.

Part 2: Create a Custom Agent (5-7 min)

Claude Code ships with a few built-in subagents (Explore for read-only research, Plan for thinking through problems). You can add your own with /agents.

Open the agent generator:

In Claude Code, type /agents. It'll walk you through a few fields.

The one that matters most is description. This is what Claude reads to decide whether to use your agent. Write it like a job posting: what does this agent do, and what kinds of requests should trigger it?

Create a read-only code reviewer:

Fill in something like this:

• Name: code-reviewer
• Description: Reviews code changes for quality, consistency with project conventions, and potential bugs. Use when asked to review a PR, check a diff, or audit a file before committing.
• Tools: Read, Glob, Grep (no write access)
• Model: sonnet (fast enough for review work)
• System prompt: You are a senior code reviewer. Focus on code quality, adherence to project conventions from CLAUDE.md, security issues, and anything that would slow down another developer trying to understand this code. Be specific. Point to line numbers. Suggest alternatives, not just problems.

After you save it, Claude Code writes the agent to .claude/agents/code-reviewer.md. Open that file and look at it. That's all an agent is: a markdown file with frontmatter.

Test it:

Make a small change to any file in your project and ask Claude:

"Review what I just changed in this file."

Watch Claude spin up the code-reviewer subagent automatically because your request matches the description. The main agent delegates. The reviewer agent reads the file, checks it against the CLAUDE.md conventions, and reports back.

The key thing to understand: Claude decides which agent to use by matching your request against the description field. Write descriptions that sound like the requests they should handle, not like the agent's internal capabilities.

Part 3: Metaprompt a GitHub Skill (7-8 min)

This is the part where Claude writes its own instructions.

A skill is a markdown file Claude loads on demand -- a reference document it can pull into context when it needs specialized knowledge. Skills are different from CLAUDE.md because they don't load automatically. You invoke them.

The meta move: instead of writing a skill yourself, you ask Claude to write it.

The prompt:

I want to create a skill for working with GitHub using the `gh` CLI. 
Please do the following:

1. Think through the most common GitHub workflows a developer does every day 
   (PRs, issues, code review, releases, working with branches)
2. For each workflow, identify the gh CLI commands that handle it
3. Write me a skill file that documents these commands with examples, 
   common flags, and any patterns worth knowing

The skill should tell you (future Claude) when to use it, what the gh CLI 
can do, and how to chain commands for multi-step tasks. 
Write it in the style of good documentation: terse, specific, with examples.

Let Claude write it. Don't edit it yet. Just read what it produces.

You should get something that covers gh pr list, gh pr create, gh pr checkout, gh issue create, gh issue list, gh run watch, gh repo clone, and probably a few chaining patterns like:

<span class="hljs-comment"># Review a PR in one move</span>
gh <span class="hljs-built_in">pr</span> checkout 123 &amp;&amp; gh <span class="hljs-built_in">pr</span> diff 123 | <span class="hljs-built_in">head</span> -100

Save it as a skill:

<span class="hljs-built_in">mkdir</span> -p .claude/skills
<span class="hljs-comment"># Save Claude&#x27;s output to:</span>
.claude/skills/github.md

Test it:

Ask Claude to use the skill for a real task:

"Using the github skill, show me all open PRs and tell me which one has been waiting the longest."

Claude should load the skill, run gh pr list --json number,title,createdAt and do the analysis.

If the skill is missing something useful, ask Claude to revise it. This is the loop: you test it against real work, you find the gaps, Claude fills them. After two or three rounds, you have a skill that's actually tuned to how you work.

The Bigger Picture

What you just built is a context stack:

• CLAUDE.md files (always loaded, scoped to directory) carry the background knowledge about your project
• Agents (loaded on demand by Claude's judgment) carry specialized execution roles
• Skills (loaded on demand by request or task) carry domain knowledge

Each layer handles a different kind of "knowing." Together, they let Claude hold your project's entire context without filling the window with things it doesn't need right now.

The GitHub skill you metaprompted is also a template. Use the same approach for any tool you work with -- AWS CLI, Terraform, Docker, your internal APIs. Ask Claude to study the tool and write the skill. You get documentation that's tuned to Claude's reasoning style instead of being written for humans.

Resources

• Claude Code documentation -- CLAUDE.md reference
• Claude Code documentation -- Sub-agents
• gh CLI documentation
• GitHub CLI cheat sheet

Code

The CLAUDE.md and agent files you created in this lab are the code. They live in .claude/ and travel with your project. Commit them.