DEV Community: Samuel Adekunle

[Boost]

Samuel Adekunle — Mon, 28 Sep 2026 12:09:37 +0000

Samuel Adekunle

Sep 28

MCP Crash Course: Model Context Protocol Explained (Simply)

#mcp #ai #techwithsam #claude

5 min read

MCP Crash Course: Model Context Protocol Explained (Simply)

Samuel Adekunle — Mon, 28 Sep 2026 08:00:00 +0000

Having to manually copy-paste context between your code environments (like IDEs) and Claude Desktop, or build fragmented, one-off custom integrations for every single new data source can be very frustrating.

That's why Model Context Protocol (MCP) was introduced and open-sourced by Anthropic in November 2024 to create a universal, standardized way for AI models to connect with external data sources, developer tools, and local systems.

Today, we're creating a complete handbook on how this MCP solution works, how to use it, and how it became one of the most useful things in AI right now.

By the end of this handbook, you'll understand:

What MCP actually is
Why it matters
How to use existing MCP servers
How to create a simple one yourself
And the key best practices

We'll keep it straightforward. Let's get into it.

What is MCP?

MCP stands for Model Context Protocol. (Official documentation)

In simple terms, it's a standard way for AI tools (like Claude, Cursor, or other AI coding assistants) to connect to external tools and data.

Think of it like USB-C for AI.

Before USB-C, every device had its own cable. Before MCP, every AI tool needed custom code to communicate with each external service. That became messy fast.

With MCP, you (or someone else) create an MCP server. Once that server exists, any compatible AI can use it.

An MCP server can offer three main things:

Tools → Actions the AI can perform (for example: "add two numbers", "create a GitHub issue", "read a file")
Resources → Data the AI can read
Prompts → Ready-made instructions

Most of the time, you'll mainly work with Tools.

That's the core idea. MCP gives AI applications a standard way to use external capabilities.

See MCP in action (Demos)

Let me show you how this looks in practice.

First, you can use existing MCP servers built by others. There are servers for the filesystem, GitHub, databases, browsers, and many other services.

You connect them to your AI tool (Claude Desktop, Cursor, etc.), and suddenly the AI can use those tools when needed.

For this handbook, I'll also show you a simple server I created so you can see exactly how it works.

Here's a basic Python MCP server:

from mcp.server.mcpserver import MCPServer

# Create the MCP server
mcp = MCPServer("Simple Demo Server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

@mcp.tool()
def get_current_time() -> str:
    """Return the current date and time."""
    from datetime import datetime
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}! Welcome to MCP."

if __name__ == "__main__":
    mcp.run()

This server exposes three simple tools: add, get_current_time, and greet.

Once this server is running and connected to your AI, you can ask things like:

"What is 95 plus 107?"
"What's the current time?"
"Greet Samuel"

The AI will automatically call the right tool and return the result.

That's the power of MCP: the AI gains new abilities without you writing custom integration code every time.

Create a simple MCP server

Now let's create one ourselves.

We'll use Python because it's simple and widely used, but you can pick from any of the available MCP SDKs.

Step 1: Install the package

uv add "mcp[cli]"

Step 2: Create a file called server.py and paste the code I showed earlier.

Step 3: Run it

You can run it directly:

python server.py

Or use the MCP development tool:

uv run mcp dev server.py

Step 4: Connect it to your AI tool

In Claude Desktop or Cursor, you add a configuration that points to this server. Once connected, the tools become available to the AI.

That's it. You now have a working MCP server.

From here, you can expand it. Instead of simple math and greetings, you can add tools that:

Read or write files
Call external APIs
Interact with your project
Query a database
Or anything else useful for your workflow

The pattern stays the same: create a tool, give it a clear description, and return a useful result.

How to use and share MCP servers

Using existing servers
Most of the time you'll just install or connect servers that already exist. You add them to your AI tool's configuration and start using them.

Sharing your own server

If you build something useful:

Put the code on GitHub
Write a clear README showing how to install and run it
Include the configuration snippet people need to connect it

That's usually enough for others (or your team) to use it.

Best Practices

Here are the most important things to remember:

Write clear tool descriptions
The AI decides when to use a tool based on the description. Make it specific and easy to understand.
Keep tools focused
One tool should do one clear job.
Be careful with permissions
Especially when giving access to files, databases, or external APIs. Only give what's needed.
Test your server
Use the MCP development tools to test before connecting it to your main AI.
Only use servers you trust
Review what tools a server exposes before connecting it.

Follow these, and you'll avoid most common problems.

That's the complete simplified handbook on MCP.

You now know:

What MCP is
How it gives AI tools new abilities
How to use existing servers
How to create a simple one yourself
And the key best practices

MCP is about giving AI access to tools and data.

In a future release, we'll look at how this pairs with Skills, which give the AI expertise on how to use those tools well.

If you build a simple MCP server after reading this, drop the GitHub link in the comments. I'd love to see it.

If this was helpful, hit like, follow, and turn on notifications.

I also offer 1-on-1 mentorship if you want help setting up AI workflows for your projects - click here.

I'll see you in the next one. Peace.

[Boost]

Samuel Adekunle — Fri, 18 Sep 2026 12:26:43 +0000

Samuel Adekunle

Sep 18

AI Agent Skills: Everything You Need to Know

#ai #skills #techwithsam #aiagents

6 min read

AI Agent Skills: Everything You Need to Know

Samuel Adekunle — Fri, 18 Sep 2026 12:25:34 +0000

In 2024, AI coding agents (Claude, Cursor, Copilot, etc.) became capable enough to do real work. Teams started writing long instruction files and system prompts. But there was no standard way to package, share, or discover them. Every team reinvented the wheel.

Today, we’re creating a complete handbook on how the solution to the issue above came about, how to use it, and how it became one of the most useful things in AI right now: Agent Skills and the platform that makes them easy to use — skills.sh.

By the end of this workflow, you will understand:

What Agent Skills actually are
How skills.sh works
How to install and use great existing skills
How to create your own skills from scratch
How to share them with your team or the world
And the best practices so your skills actually get used

This is not Flutter-only. The same system works whether you write Flutter, React, backend code, DevOps, or even content. I’ll use Flutter as one practical example, but everything here is flexible.

Let’s get into it.

What are Agent Skills and skills.sh?

An Agent Skill is a lightweight, open format for giving AI agents specialized knowledge and workflows. At its core, a skill is just a folder that contains a file called SKILL.md.

Here’s the basic structure:

my-skill/
├── SKILL.md          ← Required
├── scripts/          ← Optional
├── references/       ← Optional
└── assets/           ← Optional

The SKILL.md file has two parts:

YAML frontmatter at the top (name + description)
Markdown instructions below

The description is extremely important. Agents only load the name and description of every skill at startup. When your request matches a skill’s description, the agent then loads the full instructions. This is called progressive disclosure — it keeps the context window clean even if you have dozens of skills installed.

Now, what is skills.sh?

skills.sh is the open directory and CLI for the Agent Skills ecosystem. Think of it as the npm for AI agent capabilities. It was built by Vercel Labs and works across many agents, including Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, and more.

You install skills with a single command:

npx skills add owner/repo

That’s it. The CLI detects which agents you have and installs the skill in the right place.

You can browse popular skills on skills.sh, see a leaderboard, and discover what the community is building.

Discover on skills.sh

Community leaderboard sorted by installs
Browse by category, language, or use case
Official skills from Anthropic, Vercel, and more

Demo of some great skills

Let me show you how this looks in practice.

First, installing a skill is simple; run: npx skills add vercel-labs/agent-skills

Note: You need to have Node.js installed on your machine; download and install it.

You can also install any public repo that contains skills.

Once installed, the agent can automatically use them when relevant.

Here are four strong examples of skills.

Example 1 — PR Review (universal)

---
name: pr-review
description: "Reviews pull requests for bugs, security issues, code quality, and adherence to best practices. Use when the user asks to review a PR, check a diff, or get feedback before merging."
---

This one works on any codebase.

Example 2 — Flutter Widget Test (our case study)

---
name: flutter-widget-test
description: Generates high-quality Flutter widget tests following best practices. Use when the user asks to write tests for a Flutter widget, create widget tests, or improve test coverage for UI components.
---

This shows how you can encode framework-specific knowledge.

Example 3 — Generate Changelog

---
name: generate-changelog
description: Generates clean, professional changelog entries or release notes from git commits or PR descriptions. Use when the user asks for a changelog, release notes, or version summary.
---

Super practical for any project.

Example 4 — Brand Voice (non-code example)

---
name: brand-voice
description: Writes content following a consistent professional brand voice. Use when creating LinkedIn posts, Twitter/X threads, blog intros, product announcements, or any marketing copy.
---

This proves skills are not only for code. You can package writing style, design systems, internal processes — anything repeatable.

Build your own skill

This is the most important part of the workflow.

Creating a skill is straightforward.

Step 1: Create a folder and the required file

mkdir my-skill
touch my-skill/SKILL.md

Step 2: Write the frontmatter

The two required fields are name and description.

The description is what the agent uses to decide whether to activate the skill. Be specific. Include the kind of phrases a real user would say.

---
name: my-skill-name
description: What it does and when to use it.
Include real trigger phrases here.
---

Step 3: Write clear instructions

Good structure usually includes:

When to use this skill
When not to use it
Step-by-step process the agent should follow
Expected output format
Any edge cases or rules

Write it like you’re explaining it to a smart new teammate.

Step 4: Test with real prompts

Install locally with npx skills add ./my-skill then trigger it with exact phrases. If it doesn't activate, the description needs to be more specific.

Key tips while creating:

Start small. A focused 15–30 line skill is better than a long vague one.
Make the description do the heavy lifting for activation.
Write instructions the way you would explain the task to a smart junior developer.
Test it immediately after creating it.

Once you’re happy with it, you can install it locally and start using it right away.

Share your skills

You have two main ways to share.

1. With your team / private

Just commit the skills folder into your repository. Everyone who clones the project gets the skills.

2. Publicly with skills.sh

Push the skill to a public GitHub repository. You have two common structures:

Dedicated repo → SKILL.md sits at the root
Multi-skill repo → skills live in subfolders

# Single skill
my-repo/
└── SKILL.md

# Multi-skill
my-repo/
├── pr-review/
│ └── SKILL.md
└── changelog/
└── SKILL.md

Then anyone can install it with:

# Public: single-skill repo
npx skills add your-username/my-skill

or target a specific skill:

# Public: multi-skill repo 
npx skills add you/repo --skill name

You can also add the skills.sh badge to your README so people can see install counts.

Clear name + excellent description = more people will find and use your skill.

Best Practices

Here are the practices that separate good skills from great ones:

Write trigger-friendly descriptions — this is the #1 factor for reliable activation.
Keep skills focused — one clear job per skill. Compose multiple skills instead of making one giant skill.
Use progressive disclosure properly — put long references or examples in separate files.
Document when not to use the skill.
Test with real phrasing — try the exact words your users (or you) would actually type.
Treat skills like code — version them, review them, improve them over time.
Only install skills from sources you trust — always skim the SKILL.md and any scripts.
For teams — store shared skills in the repo so consistency is automatic.

Follow these, and your skills will actually get used instead of sitting unused.

That’s the complete handbook.

You now know:

What Agent Skills are and how progressive disclosure works
What skills.sh is and how to install skills
How to demo and evaluate existing skills
How to create your own
How to share them
And the best practices that make them effective

The biggest shift is this: instead of repeating the same instructions in every chat, you package the knowledge once and let any compatible agent use it.

If you create a skill after reading this, drop the GitHub link in the comments. I’d love to see what you build.

If you found this valuable, hit like, subscribe, and turn on notifications.

I also offer 1-on-1 mentorship if you want help setting up skills or AI workflows for your team — click here.

I’ll see you in the next one. Peace.

[Boost]

Samuel Adekunle — Thu, 10 Sep 2026 22:27:33 +0000

Samuel Adekunle

Sep 10

Automate Flutter Releases with Shorebird + GitHub Actions (Skip App Store Review)

#flutter #mobile #techwithsam #githubactions

6 min read

Automate Flutter Releases with Shorebird + GitHub Actions (Skip App Store Review)

Samuel Adekunle — Thu, 10 Sep 2026 22:27:12 +0000

A real pain point for mobile apps is waiting days or weeks for App Store and Play Store reviews whenever you need to ship a fix or a small update to users.

That exact problem is what we are solving in this article. I’ll show you exactly how to automate your Flutter releases and patches using Shorebird and GitHub Actions, so you can push updates to users in minutes instead of waiting for store review.

We are going to create a clean, production-ready CI pipeline for both full releases and instant code-push updates.

Prerequisites

Before we start, here’s what you need:

A Shorebird account and an app already set up with Shorebird
Shorebird CLI installed and logged in on your machine
A Flutter project that already has Shorebird initialized
A GitHub repository
Basic understanding of GitHub Actions

If you haven’t set up Shorebird in your Flutter app yet, check out my video on YouTube on how to set up Shorebird. This article assumes that’s already done.

Authentication Setup

The first thing we need is authentication so GitHub Actions can talk to Shorebird.

Go to the Shorebird Console → Account → API Keys → Create API Key.

Give it a clear name, e.g “GitHub Actions”, choose an expiration, and set the required permissions.

Copy the key immediately because you won’t see it again.

Now go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret.

Name it exactly: SHOREBIRD_TOKEN

Paste the key and save.

This token will be available in all your workflows as ${{ secrets.SHOREBIRD_TOKEN }}.

That’s the only authentication step you need.

Official Shorebird GitHub Actions

Shorebird provides three official GitHub Actions that make life much easier:

shorebirdtech/setup-shorebird@v1 — installs Shorebird on the runner
shorebirdtech/shorebird-release@v1 — creates a release
shorebirdtech/shorebird-patch@v1 — creates a patch

I strongly recommend using these instead of calling the CLI manually. They’re cleaner and maintained by the Shorebird team.

Release Workflow

Let’s build the release workflow first.

Create a new file in your project: .github/workflows/shorebird-release.yml

Here’s the structure:

Trigger on version tags: v1.0.0, v1.2.3, etc. or manually trigger the workflow
Set the SHOREBIRD_TOKEN as an environment variable
Pin your Flutter version (very important)
Checkout the code
Set up Java for Android (or Xcode signing for iOS)
Set up Shorebird with caching
Decode your keystore/certificates from secrets
Run the official shorebird-release action
Upload the APK, AAB, or IPA as artifacts

I’ll show both Android and iOS versions.

For Android, the key steps are decoding the keystore and creating the key.properties file from secrets.

GitHub Secrets You Need to Add for Android

Go to GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

Secret name - Value
ANDROID_KEY_ALIAS - your_key_alias
ANDROID_KEY_PASSWORD - your_key_password
ANDROID_STORE_PASSWORD - your_store_password
ANDROID_KEYSTORE_BASE64 - run `base64 -i ~/path/to/upload.jks | tr -d '\n' | pbcopy`
The keystore base64 will be copied to your clipboard; paste it into GitHub Secrets

GitHub Secrets You Need to Add for iOS

Go to GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

Secret name - Value
IOS_CERTIFICATE_BASE64 - base64 of your .p12
IOS_CERTIFICATE_PASSWORD - Password you set when exporting the .p12
IOS_PROVISIONING_PROFILE_BASE64 - base64 of com.example.app profile

For iOS, you need to import the certificate and provisioning profile into a temporary keychain.

# IOS_CERTIFICATE_BASE64 - export your .p12 from Keychain Access first, then:
base64 -i ~/path/to/distribution.p12 | tr -d '\n' | pbcopy

# IOS_PROVISIONING_PROFILE_BASE64 - download from Apple Developer Portal
base64 -i ~/path/to/YourApp_AppStore.mobileprovision | tr -d '\n' | pbcopy

You can check out this document on how to create an Apple Distribution Certificate.

Once this workflow finishes, you get signed artifacts ready to upload to the stores.

This is your normal full release path.

name: Shorebird Release

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Target platform'
        required: true
        default: 'both'
        type: choice
        options:
          - android
          - ios
          - both

jobs:
  release_android:
    name: Release Android
    if: ${{ github.event.inputs.platform == 'android' || github.event.inputs.platform == 'both' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Setup Android Keystore
        run: |
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/app/keystore.jks
          cat > android/key.properties <<EOF
          storePassword=${{ secrets.ANDROID_STORE_PASSWORD }}
          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
          storeFile=keystore.jks
          EOF
        shell: bash

      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1

      - name: Shorebird Release (Android)
        uses: shorebirdtech/shorebird-release@v1
        id: shorebird-release
        with:
          flutter-version: latest
          platform: android
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

      - name: Print Release Version
        run: echo "Released version ${{ steps.shorebird-release.outputs.release-version }}"
        shell: bash

Full release on GitHub Gist.

Patch Workflow — The Real Power

Now, the part that actually lets you skip App Store review.

Create another file: .github/workflows/shorebird-patch.yml

name: Shorebird Patch

on:
  push:
    branches:
      - main
  workflow_dispatch:
    inputs:
      platform:
        description: 'Target platform'
        required: true
        default: 'both'
        type: choice
        options:
          - android
          - ios
          - both
      release-version:
        description: 'Release version to patch (e.g. 1.0.0+1). Defaults to latest.'
        required: false
        default: 'latest'

jobs:
  patch_android:
    name: Patch Android
    if: ${{ github.event_name == 'push' || github.event.inputs.platform == 'android' || github.event.inputs.platform == 'both' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Setup Android Keystore
        run: |
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/app/keystore.jks
          cat > android/key.properties <<EOF
          storePassword=${{ secrets.ANDROID_STORE_PASSWORD }}
          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
          storeFile=keystore.jks
          EOF
        shell: bash

      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1

      - name: Shorebird Patch (Android)
        uses: shorebirdtech/shorebird-patch@v1
        id: shorebird-patch
        with:
          platform: android
          release-version: ${{ github.event.inputs.release-version || 'latest' }}
          args: --allow-asset-diffs --allow-native-diffs
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

      - name: Print Patch Number
        run: echo "Patch number ${{ steps.shorebird-patch.outputs.patch-number }}"
        shell: bash

Full release on GitHub Gist.

Trigger this one on hotfix tags, for example: v1.0.0-hotfix.1

The structure is almost identical to the release workflow, but we use the shorebird-patch action instead.

Important points:

A patch can only be applied to an existing release
Use the — staging flag first so you can preview the update
After testing with shorebird preview — track=staging, promote it to production from the Shorebird Console.

This is the real magic. Users get the fix over-the-air (OTA) in minutes. No waiting for review. No forcing them to download a new version from the store.

Recommended Development Workflow

Here’s the clean workflow I recommend (and the one Shorebird documents):

Work on features and fixes on feature branches
Open a pull request into main
CI runs formatting, analysis, and tests
Squash and merge into main (main stays always releasable)
When you’re ready for a full release → create a tag like v1.2.0 → the release workflow runs automatically
If a critical bug appears → fix it on main → cherry-pick into the release branch → create a hotfix tag like v1.2.0-hotfix.1 → the patch workflow runs
Preview on staging → promote to production

This keeps everything automated, clean, and low-risk.

Best Practices

A few important tips:

Always pin the Flutter version on releases using — flutter-version
Use — dry-run on pull requests so you catch build issues early without creating real releases or patches
Keep your SHOREBIRD_TOKEN secure — never hardcode it
For iOS environments without certificates, you can use — no-codesign (then sign later)
Shorebird automatically runs in non-interactive mode in CI when the token is present

Follow these, and your pipeline will be solid.

Resources

All of this is based on the official Shorebird documentation:

I’m also a Shorebird Ambassador, so if you have questions, drop them in the comments.

That’s it.

You now have a complete automated system:

Full releases go through the stores as usual
Critical updates and bug fixes go live to users in minutes via Shorebird

No more waiting for review every single time.

If this was useful, hit the like button, subscribe, and turn on notifications so you don’t miss the next post.

If you want personalized help setting this up for your project, you can send a DM.

I’ll see you in the next one. Peace.

[Boost]

Samuel Adekunle — Wed, 02 Sep 2026 10:19:00 +0000

Samuel Adekunle

Sep 2

AI Engineering for Flutter Developers - Production AI Engineering in Flutter

#ai #gemini #flutter #techwithsam

3 min read

AI Engineering for Flutter Developers - Production AI Engineering in Flutter

Samuel Adekunle — Wed, 02 Sep 2026 10:18:03 +0000

Over the past three articles, we've gone from fundamentals to building more reliable AI features to creating multi-agent workflows.

But there's still one big gap most tutorials never cover:
"How do you take an AI feature from 'it works on my machine' to something that's actually ready for production?"

That's what this article is all about.

We're focusing on Performance, Privacy, Security, and real-world Best Practices - the things that separate demos from production-grade AI Engineering.

What Production AI Engineering Really Means

Shipping a reliable, safe, and maintainable AI feature is a different skill.

Production AI Engineering means thinking about:

How fast it feels to the user
What data leaves the device
How secure your implementation is
How you handle failures
How you monitor and improve the system over time

We'll walk through the most important considerations every Flutter developer should know before shipping AI features.

Performance Considerations

Users are very sensitive to latency. A slow AI response can make even a smart feature feel broken.

Key things to consider:

On-device vs Cloud trade-offs
When streaming actually helps
Avoiding unnecessary AI calls
Caching results when appropriate
Choosing the right model size for the job

Privacy Best Practices

Not every piece of user data should be sent to an external AI model.

Data Minimization: Send only the minimal text snippet the prompt actually needs. Never dump an entire database record into an LLM call.
Local PII Sanitization: Strip emails, phone numbers, credit-card numbers, and home addresses before sending prompts to external APIs.
On-Device First for Sensitive Data: Health logs, financial notes, and private messages should stay on-device via TFLite or local embedding models.
Explicit User Transparency: Inform users whenever AI processes their input — and provide an opt-out toggle in Settings.

The goal is to make responsible decisions about what data leaves the user's phone.

Security Best Practices

This is an area where many developers make critical mistakes.

1. Pitfall: Committing GEMINI_API_KEY = "AIzaSy…" into lib/api_config.dart
Fix: Pass keys at build time via  --dart-define=GEMINI_API_KEY=…
or store them in server-side environment variables. 

2. Pitfall: Treating user input as trusted when building the prompt.
Fix: Treat user input as untrusted data.
Delimiter: <user_input>…</user_input>  +  enforce JSON Schema outputs.

3. Pitfall: No per-user rate-limiting on the AI endpoint.
Fix: Enforce per-user quota (e.g., 20 AI req / user / hr)
on the backend or Firebase Cloud Functions to stop wallet-depletion attacks.

Reliability, Monitoring & Evaluation

Even with good performance, privacy, and security, your AI feature still needs to be reliable.

Structured Exception Handling: Differentiate rate-limits (HTTP 429), timeouts, safety refusals, and JSON-parse errors with a custom AIException class.
Graceful Fallbacks: If the cloud model fails after retries, drop to a cached result or an on-device score - never crash, never show a raw stack trace.
Prompt Versioning: Track system-prompt revisions in git (e.g., prompts/summarizer_v2.1.txt), evaluable and roll-back-able.
Latency & Cost Telemetry: Track token usage and end-to-end response times in Firebase Analytics / Datadog / Sentry.

These practices help you understand how your AI features perform in the real world.

Production Checklist & Architecture Recommendations

Run through every box before shipping to the App Store / Play Store.

These include:

API Security
Key Restrictions
Backend Validation
Prompt Injection Defense
Rate Limiting

… and many more

Key Takeaways & Series Summary

As we close out this series, here are the biggest lessons:

AI Engineering is about much more than writing good prompts
Reliability, privacy, and security are first-class concerns
Good architecture makes AI features maintainable
Start simple, but design with production in mind

If you've followed this series from the beginning, you now have a solid foundation for building thoughtful AI features in Flutter.

You can download the AI Engineering Starter Pack with checklists, patterns, and guidance: techwithsam.dev/production-ai-engineering-in-flutter

This brings the AI Engineering for Flutter Developers series to a close.

Thank you for following along.

If this series helped you, I'd really appreciate a like and a comment.

Thanks for reading, and I'll see you in the next one.

Take care!

[Boost]

Samuel Adekunle — Fri, 28 Aug 2026 11:33:18 +0000

Samuel Adekunle

May 8

Clean Architecture in Flutter 2026 - Practical Implementation Guide

#flutter #cleancode #mobile #techwithsam

6 min read

[Boost]

Samuel Adekunle — Thu, 27 Aug 2026 16:33:40 +0000

Samuel Adekunle

Aug 27

AI Engineering for Flutter Developers - AI Agents & Workflows in Flutter

#ai #flutter #agents #techwithsamw

7 min read

AI Engineering for Flutter Developers - AI Agents & Workflows in Flutter

Samuel Adekunle — Thu, 27 Aug 2026 16:32:48 +0000

In the first two articles, we covered the fundamentals and how to build more reliable AI features using structured output, streaming, and proper error handling.

But there's a big limitation with single AI calls: they struggle with complex, multi-step tasks.

That's where AI Agents come in.

Today, we're going to build a simple but powerful multi-agent system in Flutter — specifically, a Planning Agent, a Generation Agent, and a Validation Agent.

By the end of this video, you'll understand how to design agentic workflows and implement them in real Flutter applications.

What Are AI Agents?

An AI Agent is more like giving someone a goal and letting them think, plan, and take multiple steps to achieve it, WHILE a regular LLM call is like asking a smart person one question and getting one answer.

We'll focus on a simple and practical multi-agent pattern:

Planning Agent → Breaks the user request into clear steps
Generation Agent → Executes the plan and creates the output
Validation Agent → Reviews the result and checks for quality

This pattern is extremely useful for real applications.

Designing the Workflow

We'll build a simple Smart Feature Builder,

The user gives a high level request like: 'Create a clean Flutter logins creen with email and password validation.'

Then the system works like this:

The Planning Agent creates a structured plan
The Generation Agent turns that plan into actual code or a UI description
The Validation Agent reviews the output and suggests improvements

Building the Planning Agent

The goal of this agent is to take a vague user request and turn it into a clear, structured plan.

- we define the role and system prompt for the Planning Agent
- we use structured output so we can get a clean list of steps
- then we create a Dart model for the plan
- finally, call the agent and display the result.

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';

/// Stage 1: Planning Agent
/// Takes raw user feature requests and converts them into a structured architectural plan via Gemini API.
class PlanningAgent {
  final String apiKey;
  final String modelName;

  PlanningAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are a Senior Flutter Software Architect.
Your role is to take a high-level mobile/web feature request and generate a clean, structured architectural plan.

You must respond ONLY with a valid JSON object matching this exact schema:
{
  "title": "String - Concise title of the feature plan",
  "overview": "String - Executive summary of the architectural strategy",
  "targetPlatform": "String - Target platforms (e.g. Flutter Web, iOS & Android)",
  "componentsToBuild": ["List of String - Individual UI components, widgets, or services to build"],
  "implementationSteps": ["List of String - Sequential step-by-step engineering tasks"],
  "riskConsiderations": ["List of String - Potential state management, security, performance or edge case risks"]
}
''';

  Future<FeaturePlan> planFeature(String prompt) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final request = GenerateContentRequest(
      contents: [Content.text('Feature Request:\n$prompt')],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.2,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Planning Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return FeaturePlan.fromJson(jsonMap);
  }
}

Building the Generation Agent

This agent takes the structured plan and actually produces the output, in our case, Flutter-related code/content suggestions.

- first, we create the Generation Agent with a clear role
- then pass the plan from the previous agent
- generate the final output
- show how we keep the response structured and useful

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';
import '../models/generated_feature_code.dart';

/// Stage 2: Generation Agent
/// Takes the architectural FeaturePlan and user request, then generates complete, production-ready Flutter code via Gemini API.
class GenerationAgent {
  final String apiKey;
  final String modelName;

  GenerationAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are an expert Lead Flutter Engineer.
Your task is to take an Architectural Feature Plan and write production-ready, clean, well-formatted Flutter Dart code.

You must respond ONLY with a valid JSON object matching this exact schema:
{
  "title": "String - Title of the generated feature code",
  "explanation": "String - Clear explanation of key implementation patterns and Dart features used",
  "flutterCode": "String - Complete, fully functioning, syntactically correct Flutter Widget Dart code",
  "dependencies": ["List of String - Required packages in pubspec.yaml (e.g. google_fonts, flutter_animate)"]
}
''';

  Future<GeneratedFeatureCode> generateCode({
    required String userPrompt,
    required FeaturePlan plan,
  }) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final promptInput = '''
User Feature Request:
$userPrompt

Architectural Plan:
${plan.toFormattedJson()}
''';

    final request = GenerateContentRequest(
      contents: [Content.text(promptInput)],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.3,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Generation Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return GeneratedFeatureCode.fromJson(jsonMap);
  }
}

Building the Validation Agent

This agent acts like a reviewer. It checks the output from the Generation Agent for issues, missing pieces, or areas for improvement.

- again, we create the Validation Agent
- feed it the original request + the generated output
- get structured feedback
- optionally show a simple improvement loop

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';
import '../models/generated_feature_code.dart';
import '../models/validation_report.dart';

/// Stage 3: Validation Agent
/// Reviews generated code against the original user prompt and architectural plan via Gemini API.
class ValidationAgent {
  final String apiKey;
  final String modelName;

  ValidationAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are a Lead Code Auditor and Security Reviewer for Flutter applications.
Your job is to audit generated Flutter code against the user request and architectural plan.

You must evaluate code quality, completeness, error handling, accessibility, and performance.
You must respond ONLY with a valid JSON object matching this exact schema:
{
  "qualityScore": 92, // Integer between 0 and 100
  "isPassed": true, // Boolean - true if qualityScore >= 75
  "identifiedIssues": ["List of String - Specific flaws, missing validations, or anti-patterns"],
  "improvementSuggestions": ["List of String - Actionable code quality or performance recommendations"],
  "refinedCodeSnippet": "String or Null - Improved/corrected snippet fixing identified issues"
}
''';

  Future<ValidationReport> validateOutput({
    required String userPrompt,
    required FeaturePlan plan,
    required GeneratedFeatureCode generatedCode,
  }) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final promptInput = '''
Original Request:
$userPrompt

Architectural Plan:
${plan.toFormattedJson()}

Generated Code to Audit:
${generatedCode.toFormattedJson()}
''';

    final request = GenerateContentRequest(
      contents: [Content.text(promptInput)],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.1,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Validation Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return ValidationReport.fromJson(jsonMap);
  }
}

Putting It All Together

We need to connect everything into one workflow.

We will create a simple orchestrator that:
1. Calls the Planning Agent
2. Passes the plan to the Generation Agent
3. Sends the result to the Validation Agent
4. Displays the final output and feedback

/// Orchestrator Service
/// Coordinates the multi-agent pipeline: Planning -> Generation -> Validation
class AgentOrchestrationService extends ValueNotifier<AgentWorkflowState> {

  ...

  Future<void> runWorkflow(String prompt, {required String apiKey}) async {
    if (prompt.trim().isEmpty) return;

    _addLog('Orchestrator', 'Workflow started for prompt: "$prompt"');

    try {
      // -----------------------------------------------------------------------
      // STAGE 1: Planning Agent
      // -----------------------------------------------------------------------
      _addLog('Planning Agent', 'Analyzing request & composing architectural plan...');
      final planningAgent = PlanningAgent(apiKey: apiKey);
      final plan = await planningAgent.planFeature(prompt);

      value = value.copyWith(
        stage: AgentStage.generating,
        plan: plan,
      );
      _addLog('Planning Agent', 'Plan generated successfully: "${plan.title}"', payload: plan.toFormattedJson());

      // -----------------------------------------------------------------------
      // STAGE 2: Generation Agent
      // -----------------------------------------------------------------------
      _addLog('Generation Agent', 'Writing Flutter code & module dependencies...');
      final generationAgent = GenerationAgent(apiKey: apiKey);
      final generatedCode = await generationAgent.generateCode(
        userPrompt: prompt,
        plan: plan,
      );

      value = value.copyWith(
        stage: AgentStage.validating,
        generatedCode: generatedCode,
      );
      _addLog('Generation Agent', 'Code generated successfully (${generatedCode.flutterCode.length} chars)', payload: generatedCode.toFormattedJson());

      // -----------------------------------------------------------------------
      // STAGE 3: Validation Agent
      // -----------------------------------------------------------------------
      _addLog('Validation Agent', 'Auditing code quality, security & accessibility...');
      final validationAgent = ValidationAgent(apiKey: apiKey);
      final validationReport = await validationAgent.validateOutput(
        userPrompt: prompt,
        plan: plan,
        generatedCode: generatedCode,
      );

      _tickerTimer?.cancel();

      value = value.copyWith(
        stage: AgentStage.completed,
        validationReport: validationReport,
      );
      _addLog('Validation Agent', 'Audit complete. Quality Score: ${validationReport.qualityScore}/100 (Passed: ${validationReport.isPassed})', payload: validationReport.toFormattedJson());
      _addLog('Orchestrator', 'Multi-Agent pipeline executed successfully!');
    } catch (e) {
      _tickerTimer?.cancel();
      _addLog('Orchestrator', 'Pipeline failed: $e');
      value = value.copyWith(
        stage: AgentStage.failed,
        error: e,
      );
    }
  }
}

The full source code is on GitHub: github.com/techwithsam/ai_engineer_for_flutter_devs/tree/video-3

Recap & Key Takeaways

Quick summary of what we covered:

AI Agents allow us to handle multi-step tasks much better than single prompts
The Planning → Generation → Validation pattern is simple but powerful
Structured output is critical when agents need to communicate
Keeping the architecture clean makes these systems maintainable

This is a foundational pattern you can expand in many directions.

If you haven't already, download the free AI Engineering Starter Pack - I've updated it with the code and patterns from this article.

Here: techwithsam.dev/ai-starter-kit-3

Just enter your email, and it will be sent to you instantly.

In the next and final video of this series, we'll focus on Production AI Engineering - covering performance, privacy, security, evaluation, and best practices for shipping AI features in real Flutter apps.

If you found this valuable, please like and drop a comment.

I'd love to know: What kind of multi-agent workflow would you like to see next?

Thank you for following. I'll see you in the final one.

Take care!

AI Engineering for Flutter Developers — Building Reliable AI Features in Flutter

Samuel Adekunle — Wed, 19 Aug 2026 16:13:10 +0000

Building a reliable AI feature that works well in production is not so easy; it's a completely different skill.

For this part 2, we're going to focus on three critical skills every AI Engineer needs, i.e

Mastering Structured AI Outputs
Real-Time Streaming
Building a Robust Error Handling System

By the end, we will know how to build AI features that are cleaner, more predictable, and much more enterprise-ready.

What You'll Learn in This Part:

Why free-text AI responses are dangerous to production Flutter Apps
How to force structured, typed responses using Gemini
How to implement streaming for better user experience in Flutter
How to handle AI failures gracefully in Flutter

Structured Output

Let's start with Structured Output.

When you ask an AI model a question, by default, it returns free text (plain text), which is flexible but dangerous and hard to work with in real applications.

Structured Output allows the model to return clean, predictable data, usually in JSON format, just like when we are integrating an endpoint.

Here is an example of how to do this properly with Gemini in Flutter.

Future<ArticleBlueprint> generateStructuredBlueprint(
    String topicPrompt, {
    void Function(int attempt, Duration delay, Exception error)? onRetry,
  }) async {

    return RetryHelper.retryWithBackoff<ArticleBlueprint>(
      onRetry: onRetry,
      maxAttempts: 3,
      action: () async {
        GoogleAIClient? client;
        try {
          // 1. Initialize client using googleai_dart
          client = GoogleAIClient(
            config: GoogleAIConfig(
              authProvider: ApiKeyProvider(apiKey),
            ),
          );

          // 2. Build Structured JSON prompt enforcing strict schema
          final systemPrompt = '''
You are a technical content architect. Generate a structured JSON blueprint for a technical article or feature guide.

STRICT JSON SCHEMA REQUIREMENT:
Return ONLY a valid JSON object with the following fields:
- "title": String (compelling article title)
- "overview": String (concise 2-3 sentence overview)
- "difficulty": String ("Beginner", "Intermediate", or "Advanced")
- "estimatedReadingMinutes": Integer
- "tags": Array of Strings
- "keyConcepts": Array of Strings (up to 4 bullet points)
- "implementationSteps": Array of Strings (step-by-step implementation guide)
- "codeSnippet": String (short code example)

Topic to generate blueprint for:
"$topicPrompt"
''';

          // 3. Make API request using client.models.generateContent
          final response = await client.models.generateContent(
            model: modelName,
            request: GenerateContentRequest(
              contents: [
                Content(
                  parts: [TextPart(systemPrompt)],
                  role: 'user',
                ),
              ],
            ),
          );

          // 4. Extract generated text payload
          final candidate = response.candidates?.firstOrNull;
          if (candidate?.finishReason == FinishReason.safety ||
              candidate?.finishReason?.name.toLowerCase() == 'safety') {
            throw const SafetyRefusalAIException(
              'The requested topic was flagged by Gemini safety filters.',
            );
          }

          final parts = candidate?.content?.parts ?? [];
          final rawText = parts
              .whereType<TextPart>()
              .map((p) => p.text)
              .join('\n');

          if (rawText.isEmpty) {
            throw const SchemaParsingAIException(
              'Received empty output from Gemini model.',
              rawOutput: '',
            );
          }

          // 5. Clean markdown code blocks & parse JSON
          final cleanJsonText = _cleanMarkdownJson(rawText);
          final jsonMap = jsonDecode(cleanJsonText) as Map<String, dynamic>;

          // 6. Deserialize into strongly-typed Dart model
          return ArticleBlueprint.fromJson(jsonMap, rawText);
        } catch (e) {
          throw _translateException(e);
        } finally {
          client?.close();
        }
      },
    );
  }

This alone will make the AI feature more reliable.

Streaming Responses

Next up is Real-Time Streaming

Nobody likes staring at a loading spinner while waiting for a long AI response. With streaming, we can let the text appear gradually, just like a typewriter, which feels much more natural and responsive.

Let's implement streaming with Gemini in Flutter

/// Token Streaming (`streamGenerateContent`).
  ///
  /// Yields incremental text tokens as they arrive from Gemini in real-time.
  Stream<String> streamTextContent(String prompt) async* {
    GoogleAIClient? client;
    try {
      client = GoogleAIClient(
        config: GoogleAIConfig(
          authProvider: ApiKeyProvider(apiKey),
        ),
      );

      final stream = client.models.streamGenerateContent(
        model: modelName,
        request: GenerateContentRequest(
          contents: [
            Content(
              parts: [TextPart(prompt)],
              role: 'user',
            ),
          ],
        ),
      );

      await for (final response in stream) {
        final candidate = response.candidates?.firstOrNull;
        final parts = candidate?.content?.parts ?? [];
        final token = parts
            .whereType<TextPart>()
            .map((p) => p.text)
            .join();

        if (token.isNotEmpty) {
          yield token;
        }
      }
    } catch (e) {
      throw _translateException(e);
    } finally {
      client?.close();
    }
  }

As simple as that…

Error Handling & Resilience

This is the part most devs skip, and it's one of the reasons many AI features break in production.

AI calls can fail for many reasons:

Network issues
Rate limits
Invalid responses
Timeouts
Model refusing the request

Let's create a simulation of a proper error handling system that includes:

Clear error types
Retry logic
Meaningful feedback to the user
Fallback behaviour

/// DEMO HELPER: Simulates intentional fault cases.
  Future<ArticleBlueprint> simulateFault(String faultType) async {
    await Future.delayed(const Duration(milliseconds: 600));

    switch (faultType) {
      case '429_rate_limit':
        throw const RateLimitAIException(
          'HTTP 429: Too Many Requests. Gemini rate limit reached.',
          retryAfter: Duration(seconds: 5),
        );
      case 'network_timeout':
        throw const NetworkAIException(
          'SocketException: Connection timed out while reaching api.generativeai.google',
        );
      case 'schema_invalid':
        throw const SchemaParsingAIException(
          'FormatException: Missing mandatory "title" key in JSON payload.',
          rawOutput: '{"overview": "Broken JSON example without title"}',
        );
      case 'safety_refusal':
        throw const SafetyRefusalAIException(
          'Prompt blocked by Gemini Safety Classifier Policy.',
        );
      default:
        throw const UnknownAIException('Simulated unknown exception.');
    }
  }

Now we can combine everything we've learned into a more complete example.

Source code on GitHub

techwithsam / ai_engineer_for_flutter_devs

AI Engineering for Flutter Devs 2026 - TechWithSam

AI Engineering for Flutter Developers – Smart Text Analyzer

Free resource from Tech With Sam — companion repo for the AI Engineering for Flutter Developers YouTube series.

📦 What's in This Repo

Folder / File	Contents
`/lib/services`	Cloud Gemini (`GeminiService`), On-Device TFLite (`OnDeviceClassifierService`), & Resilient AI Engine (`ResilientAIService`, `RetryHelper`)
`/lib/models`	Data models (`TextAnalysisResult`), Structured Output schemas (`ArticleBlueprint`), & Custom AI Exceptions (`ai_exceptions.dart`)
`/lib/widgets`	UI components: Gemini/On-Device cards, `StreamingOutputWidget`, `StructuredBlueprintCard`, & `ErrorResilienceBanner`
`/lib/theme`	Dark & light mode brand theme system (`AppTheme`)
`/lib/part_two_app.dart`	Video 2 entry point & studio screen for Structured Output, Token Streaming, and Fault Injection testing
`/lib/main.dart`	Main root app launcher coexisting across all video series modules

🚀 Quick Setup

# 1. Clone the repo
git clone https://github.com/techwithsam/ai_engineer_for_flutter_devs.git
# 2. Navigate into the project
cd ai_engineer_for_flutter_devs

# 3. Get dependencies
flutter

…

View on GitHub

Recap & Key Takeaways

Today we covered:

Always prefer Structured Output when you need predictable data
Use streaming to improve perceived performance
Treat error handling as a priority and first-class citizen

These three practices will immediately raise the quality of any AI feature you build in Flutter.

If you haven't already, download the free AI Engineering Starter Pack — I've updated it with the code and patterns from this article.

Here: techwithsam.dev/ai-starter-kit-2

Just enter your email, and it will be sent to you instantly.

If you found this valuable, please hit the like clap, follow, and turn on notifications so you don't miss the rest of this series.

In the next release, we'll go into AI Agents and Workflows

Drop a comment and tell me: What's one AI feature you want to build in your Flutter app?

Thank you for following. I'll see you in the next one.

Take care!