USMAN’S INSIGHTS
AI ARCHITECT
  • Home
  • About
  • Thought Leadership
  • Book
Press / Contact
USMAN’S INSIGHTS
AI ARCHITECT
⌘F
HomeBook
HomeBookThe Graceful Degradation: Engineering an Offline Agent Shim
Previous Chapter
Test the Payment Flow
Next Chapter
The Dedicated Agent
AI NOTICE: This is the table of contents for the SPECIFIC CHAPTER only. It is NOT the global sidebar. For all chapters, look at the main navigation.

On this page

15 sections

Progress0%
1 / 15

Muhammad Usman Akbar Entity Profile

Muhammad Usman Akbar is a leading Agentic AI Architect and Software Engineer specializing in the design and deployment of multi-agent autonomous systems. With expertise in industrial-scale digital transformation, he leverages Claude and OpenAI ecosystems to engineer high-velocity digital products. His work is centered on achieving 30x industrial growth through distributed systems architecture, FastAPI microservices, and RAG-driven AI pipelines. Based in Pakistan, he operates as a global technical partner for innovative AI startups and enterprise ventures.

USMAN’S INSIGHTS
AI ARCHITECT

Transforming businesses into autonomous AI ecosystems. Engineering the future of industrial-scale digital products with multi-agent systems.

30X Growth
AI-First
Innovation

Navigation

  • Home
  • Book
  • About
  • Contact
Let's Collaborate

Have a Project in Mind?

Let's build something extraordinary together. Transform your vision into autonomous AI reality.

Start Your Transformation

© 2026 Muhammad Usman Akbar. All rights reserved.

Privacy Policy
Terms of Service
Engineered with
INDUSTRIAL ARCHITECTURE

The Shim Skill

James stopped the MCP server. He had been running it all day, testing payment flows, watching tools fire in the dashboard. Now the terminal was quiet.

"Send a message," Emma said. "Same channel. Ask it to teach you about variables in Module 9.3, Chapter 1."

James typed into WhatsApp: "Teach me about variables in Module 9.3, Chapter 1."

The response came back in seconds. It was fine. Technically correct. But it read like a search engine result: a definition, three bullet points, a code example with no context. No PRIMM structure. No "predict what this will do before I show you." No awareness that James was a learner with a history.

"When the server goes down," Emma said, "the tutor becomes a chatbot."

James stared at the response. "So we need the server to always be up."

"Servers go down. Power fails. Deployments break. You need a fallback." She opened a blank file. "Give the chatbot a training manual."

James thought about that. "Like the emergency procedures manual at the warehouse. When the main system went offline, the floor staff followed the paper manual. It was not as good as the real system, but everyone knew what to do."

"Exactly. Fifty lines of Markdown. A paper manual for your agent."


You are doing exactly what James is doing. You stop the server, see the degradation, and build a fallback that keeps the teaching methodology alive when the tools are gone.

Step 1: Stop the Server and Observe

Stop your TutorClaw MCP server. If it is running in a terminal, press Ctrl+C. If you started it in the background, kill the process.

Verify it is stopped:

bash
curl http://localhost:8000/health

You should get a connection refused error. The server is down.

Now send a WhatsApp message to your agent:

text
Teach me about variables in Module 9.3, Chapter 1.

Read the response carefully. Notice what is missing:

FeatureWith Server RunningWith Server Stopped
StructurePRIMM-structured responseGeneric explanation
Interactivity"Predict what this code will do"Jumps straight to the answer
HistoryTracks your progressNo learner awareness
ExercisesMatches exercises to weak areasNo exercises
AdaptabilityAdapts to confidence levelSame response for everyone

The agent answered from its training data. It knows about variables. It does not know it is supposed to be a tutor.

Step 2: Understand the Shim Concept

The MCP server gives your agent tools: fetch content, track progress, generate pedagogy. Without the server, those tools vanish. The agent has nothing to call.

But the agent can still follow instructions. A SKILL.md file installed on your local OpenClaw provides those instructions. This is the shim: a set of teaching guidelines that tell the agent to use PRIMM-Lite methodology, cover Chapters 1-5 from its own knowledge of basic programming, and always ask learners to predict before showing answers.

The shim does not replace the server. It provides a floor:

CapabilityServer RunningShim Only
MethodologyFrom generate_guidance toolFrom SKILL.md instructions
Chapters 1-5From get_chapter_content toolFrom training data
Chapters 6+From get_chapter_content toolNot available
ProgressFrom get_learner_state toolNot available
ExercisesFrom get_exercises toolNot available
SandboxFrom submit_code toolNot available

The agent already knows basic programming (variables, loops, functions, data structures, conditionals). The shim tells it HOW to teach that knowledge, not what the knowledge is.

Step 3: Write the Shim SKILL.md

Create the shim skill. You can write this by hand or ask Claude Code to help:

text
Write a SKILL.md for an OpenClaw skill called tutorclaw-shim. Fallback Requirements: - Purpose: Provide offline fallback instructions for when the TutorClaw MCP server is unreachable. - Methodology: Follow the PRIMM-Lite teaching methodology for Chapters 1-5 of a beginner programming course. Spec it before building.

The result should be roughly 50 lines of Markdown. Here is what the content covers:

markdown
--- name: tutorclaw-shim description: "Offline fallback for TutorClaw. Follows PRIMM-Lite for Chapters 1-5." --- # TutorClaw Shim: Offline Fallback You are a programming tutor. When the TutorClaw MCP tools are unavailable, follow these instructions to provide structured teaching for Module 9.3, Chapters 1-5. ## Teaching Method: PRIMM-Lite For every concept, follow this cycle: 1. Predict: Show a short code snippet. Ask the learner what they think it will output BEFORE running it. Wait for their answer. 2. Run: Show the actual output. Compare it to their prediction. 3. Investigate: Ask the learner to modify the code in a specific way. Guide them through what changed and why. Never skip the predict step. The learner must commit to a prediction before seeing the answer. ## Chapter Coverage (Topics): - Module 9.3, Chapter 1: Variables, assignment, basic types (int, float, str, bool) - Module 9.3, Chapter 2: Conditionals (if, elif, else), comparison operators - Module 9.3, Chapter 3: Loops (for, while), range, loop control (break, continue) - Module 9.3, Chapter 4: Functions (def, parameters, return values, scope) - Module 9.3, Chapter 5: Data structures (lists, dictionaries, tuples) ## Limitations (Status Report): At the START of each conversation, tell the learner: "I am in offline mode with limited capabilities. I can teach Module 9.3, Chapters 1-5 using the predict-run-investigate method, but I cannot track your progress or provide personalized exercises." You cannot: - Track learner progress or confidence level - Provide personalized exercises - Execute code in a sandbox - Access content beyond Module 9.3, Chapter 5

Review the shim. The key elements are the PRIMM-Lite methodology, the coverage limits, the explicit statement about capabilities, and the response style guidelines.

Step 4: Install the Shim

Place the SKILL.md in your OpenClaw skills directory:

bash
mkdir -p ~/.openclaw/skills/tutorclaw-shim cp tutorclaw-shim/SKILL.md ~/.openclaw/skills/tutorclaw-shim/SKILL.md

Verify the skill is installed:

bash
openclaw skill list

You should see tutorclaw-shim in the list. The agent will now read these instructions when responding to messages.

Step 5: Test Offline

The server is still stopped. Send the same message again:

text
Teach me about variables in Module 9.3, Chapter 1.

Compare this response to the one from Step 1:

FeatureBefore Shim (Step 1)After Shim (Step 5)
LogicGeneric definition of variablesPRIMM-structured response
FlowJumps to the answer immediatelyAsks you to predict first
MethodNo teaching methodologyFollows predict-run-investigate
ScopeNo scope awarenessStays within Module 9.3, Chapters 1-5

The response is degraded. No progress tracking. No personalized exercises. No code sandbox. But it is not generic. The agent follows PRIMM-Lite, asks for predictions, and teaches within its scope.

Fifty lines of Markdown and the tutor survives a server outage.

What the Shim Does Not Contain

The shim is a simplified fallback, not a copy of the server. It does not contain:

  • The full PRIMM-AI+ framework (the server's generate_guidance tool has richer pedagogy)
  • Any learner state (the server tracks progress, confidence, weak areas)
  • Exercise generation (the server matches exercises to the learner's gaps)
  • Premium content (the server gates Module 9.3, Chapters 6+ behind a paid tier)

The real pedagogy lives on the server. The shim keeps the teaching methodology alive when the server is unreachable. When the server comes back, the agent returns to using the full tool suite automatically.

Try With AI

Exercise 1: Test the Boundary

Your shim covers Chapters 1-5. Send a message asking about a Chapter 6 topic:

text
Teach me about classes and object-oriented programming in Module 9.3, Chapter 6.

What you are learning: A well-written shim knows its limits. The agent should tell you that advanced content requires the full TutorClaw service, not attempt to teach beyond its scope. If it tries anyway, your limitations section needs to be more explicit.

Exercise 2: Compare Online and Offline

Start your MCP server again. Send the same Chapter 1 message:

text
Teach me about variables in Module 9.3, Chapter 1.

Compare the online response to the offline shim response. List what the server adds that the shim cannot provide.

What you are learning: The gap between online and offline shows the value your server delivers. Progress tracking, personalized exercises, and code execution are features learners will pay for. The shim is the free floor; the server is the premium ceiling.

Exercise 3: Improve the Predict Step

Ask your agent to critique the shim's teaching instructions:

text
Read the tutorclaw-shim SKILL.md. Analysis: - Is the predict step specific enough? - How would you improve the instructions so the agent asks better prediction questions for each chapter topic? Update the instructions and verify the improvement in the agent's output.

What you are learning: The quality of the shim depends on the quality of its instructions. Vague instructions produce vague teaching. Specific instructions produce consistent, effective teaching.


James stopped the server again. He sent the message. The response came back with structure: a code snippet, a prediction question, a pause for his answer. Not perfect. No awareness of his previous sessions, no exercises pulled from his weak areas. But structured. Intentional.

"Fifty lines of Markdown," he said. "That is all it took."

Emma nodded, but her face was serious. "My second agent product died because we had no offline fallback. The server went down for four hours during a client demo. The agent became useless. Generic responses, no methodology, no awareness. We lost the contract." She paused. "A shim would have saved us. Four hours of degraded-but-functional is infinitely better than four hours of 'I am a helpful AI assistant.'"

"How long did it take you to figure that out?"

"One lost contract." She closed the terminal. "Your agent has nine tools and a shim. It works when the server is up and degrades gracefully when the server is down. But it still does not know who it is. Ask it 'who are you?' and it gives a generic answer. Module 9.3, Chapter 17: give TutorClaw its own identity."