A trendy male software engineer with dark hair, glasses, and a beard teaches at a chalkboard covered in DevOps diagrams and GitHub CLI commands. He gestures with chalk while a humanoid robot, seated at a wooden school desk, attentively takes notes. The scene blends a traditional classroom aesthetic with modern AI and coding concepts.

Teach Your AI Assistant New Tools Without a Full MCP Using claude.md

Modern AI assistants can be powerful collaborators—especially when they understand the tools in your local environment. But teaching them how to use those tools effectively often feels like it requires heavyweight integration or custom Model Context Protocols (MCPs). What if there was a simpler, more flexible way?

In this article, I’ll walk you through how I used a lightweight claude.md file to teach Claude Code how to use the GitHub CLI (gh)—unlocking an autonomous development flow where my AI assistant can manage and move GitHub issues forward, write and stage code, and pause for human review before committing and continuing its work.

Why Not Use MCP?

An MCP is useful for fully codifying how a tool works with an AI, especially when it's being shared across teams or organizations. But sometimes, all you need is context—not an entire protocol spec.

If the tool (like gh) is already installed on your local machine, and your AI assistant can access a well-written, structured guide for using it, that's often enough to get started. That's where the claude.md file shines.

The Workflow: AI as a Development Assistant

I wanted to see if I could get Claude to manage a GitHub issue and its sub-issues autonomously. The goal was to have it:

  • Assign itself to a parent issue
  • Discover sub-issues
  • Write and stage code
  • Pause for my review before committing
  • Update the GitHub issue with progress
  • Close the issue when done
  • Move on to the next sub-issue

I imagined this could be a very intuitive workflow, like leading a development team through a project.

I developed a good way to teach the AI by using introspection and context, and then asking the ai to update its own instructions. This way, I could avoid the complexity of a full MCP. It worked surprisingly well!

Now I begin my workflow by creating a GitHub issue for a new large feature, and break it down into smaller sub-issues. I then assign the parent issue to my AI assistant, Claude, and let it take over.

A screenshot of a GitHub issue assigned to an AI assistant.
Claude assigned to a GitHub issue

Here’s what my AI-powered dev assistant can now do with a single parent GitHub issue:

  1. Start the issue
    Assigns me as the owner, marks it as "In Progress" on the project board, and reads the issue context.

  2. Discover Sub-Issues
    Finds all related subtasks using gh issue list --search, gathers descriptions, and builds an execution sequence.

  3. Write and Stage Code
    Works through each sub-issue, writing and staging changes with git, while presenting git diff --staged output for review.

  4. Review & Commit Flow
    Waits for my approval before committing. Once approved, it commits with a clean conventional message and moves on.

    A screenshot of a git staged changes completed by an AI ready for review.
    Claude waiting for review before committing changes

  5. Update Progress
    Updates the GitHub issue with progress notes, closes it upon completion, and moves on to the next subtask.

    A screenshot of a GitHub issue being updated by an AI assistant.
    Claude automatically updating a GitHub issue

Watching the project board update on its own is a surreal, satisfying experience—and a testament to the power of scoped task delegation in AI workflows.

A screenshot of a GitHub project board being updated by an AI assistant. The board shows various columns for different stages of development, with cards moving automatically as tasks are completed.
Claude automating GitHub issue management

Why It Works

This approach works well for several reasons:

  • Context Over Configuration
    By clearly defining tool usage patterns in claude.md, the AI can pick up how to interact with new tools purely through instruction and inference.

  • Small Task Focus
    AI models thrive on small, well-defined objectives. Assigning an issue with sub-tasks provides a natural scaffold that avoids overloading the model.

  • Human-in-the-Loop
    Pausing for review before commits allows for course corrections and collaborative improvements—leading to better code and fewer surprises.

  • No Special Plugins or Frameworks Needed
    If your machine has the CLI tools, and the AI knows how to use them, you’re good to go.

The claude.md Strategy

Here’s the wildest part: I didn’t write the claude.md file myself.

Instead, I used the AI model to figure out the right workflows by asking it questions like:

  • “Can you use the GitHub CLI to view this issue?” (and pasted a link)
  • “Now can you use GitHub CLI to find all sub-issues?”
  • “Can you check if the issue is on a project board?”
  • “How would you update its status?”

When it didn’t find all the sub-issues or got something wrong, I’d nudge it—giving hints or asking clarifying follow-ups. Once the AI consistently succeeded at the task and met my expectations, I gave it this instruction:

“Now update claude.md with instructions so you can repeatably and reliably perform this task.”

And it did. 🤯

The result was a self-generated, contextual guide—written by the AI, for the AI—on how to interact with the GitHub CLI and manage issues in a reproducible way.

Here’s a slice of what Claude wrote:

## Working with GitHub Issues

- Use `gh issue view <number>` to get context
- Discover sub-issues with:
  - `gh issue list --search "mentions:#<parent>"`
  - `gh issue list --search "linked:<parent>"`
- Assign and update status:
  - `gh issue edit <number> --add-assignee @me`
  - Use project commands to set status fields
- Only commit after explicit user review
- Always close issues with completion summary

2025-04-23