DEV Community: Peng Qian

The concept of Loop Engineering has been getting a lot of buzz lately, so I decided to give it a shot in OpenCode. The results were surprisingly good:

Peng Qian — Thu, 16 Jul 2026 07:41:44 +0000

Peng Qian

Jul 16

How I Built a Fully Automated Coding Loop in OpenCode

#ai #programming #coding #llm

4 min read

How I Built a Fully Automated Coding Loop in OpenCode

Peng Qian — Thu, 16 Jul 2026 07:41:10 +0000

Introduction

If you've been following the AI agent space recently, you've probably heard the term Loop Engineering. Claude Code and OpenClaw both mention it.

But nobody really explains what it means.

Until Andrew Ng posted a clear breakdown of what Loop Engineering actually is. That post gave me the direction I needed to build it inside OpenCode.

What Andrew Ng Says About the Coding Loop

Andrew Ng's explanation centers around this diagram:

Three loops, simply put:

The first loop is the code agent's implementation loop. You give the agent a product spec and a measurable target. The agent starts building features on its own, runs tests, and keeps iterating until every requirement in the spec is met.
The second loop is the engineer feedback loop. Here the engineer acts as QA for their own product. They test what the coding agent built, and check if it matches their vision. If something is off, they write a new spec and kick off another round in the first loop.
The third loop is the external feedback loop. Once the engineer is happy with the product, it goes to the open-source community or gets handed to a product team. Real user feedback comes in. The engineer collects that feedback regularly, feeds it back into the engineer feedback loop, and from there back into the code implementation loop.

All three loops keep running. With AI in the mix, they push the product forward until it gets to where it needs to be.

My Attempts

Following Professor Andrew Ng's breakdown, I gave it a try in OpenCode. I built a /goal command that lets users just type in what they want the AI to do, and the AI will kick off a coding loop to get it done automatically.

I tested this command out and honestly, the results were way better than I expected.

Here are some of the test scenarios I ran:

1. Write a Fibonacci script

This test checks whether the agent picks the best algorithm. The prompt is:

/goal Write a Fibonacci calculation script with the best possible performance.

2. Build a Tower of Hanoi web game

Everyone knows this game. You could honestly just prompt an LLM directly and get it built. But that predictability is exactly what makes it useful for testing whether each step of the coding loop is working correctly.

/goal Build a playable Tower of Hanoi web game.

3. Build a chess web game

Maybe you are not impressed by the Tower of Hanoi example, since a regular prompt to any frontier model can do the same thing without a coding loop. Fair. The chess game experiment is something you should actually try for yourself.

/goal Build a playable chess web game. 
Include easy, medium, and hard difficulty levels. 
No online multiplayer needed. 
Use a Python backend as the AI engine.

4. A typing practice game for kids

/goal I want to build a typing practice web app for kids. 
At the bottom of the screen are 9 keys representing the positions of 10 fingers, with the thumbs sharing a wider spacebar key that takes up two slots. 
Above those 9 keys is a gradient-transparent rectangle. 
Letters fall down from the top toward that rectangle, aligned to their matching key positions. 
Press the right key as the letter enters the zone and it counts as a hit, triggering a hit effect. 
Consecutive correct hits build up increasingly dramatic effects. 
The falling speed gradually increases. 
At the top of the screen is a scoreboard that adds 1 point for each hit, with a pop animation. 
The whole thing should feel exciting and dopamine-triggering, with plenty of visual encouragement.

Pretty cool, right? Feeling curious?

Go ahead and check out my latest article No Plugins Needed, I Built a Fully Automated Coding Loop in OpenCode for the full tutorial, which covers:

My implementation approach.
How to use it.
The complete source code.

It's all free, so what are you waiting for?

The essence of prompt engineering isn't about feeding the model more information. It's about helping both the model and humans put their limited attention in the right place.

Peng Qian — Wed, 01 Jul 2026 06:14:54 +0000

Peng Qian

Jul 1

Why Well-Written Prompts Are Almost Always Structured

#ai #programming #productivity #tutorial

2 min read

Why Well-Written Prompts Are Almost Always Structured

Peng Qian — Wed, 01 Jul 2026 06:13:02 +0000

There's been endless debate about which language format prompts should be written in. Last year it was Markdown vs. JSON, this year it's Markdown vs. HTML.

But if you ask me, the answer has never been about the format itself. The reason why some prompts work so well all points to the same thing: structure.

The essence of prompt engineering isn't about feeding the model more information. It's about helping both the model and humans put their limited attention in the right place. Structured languages happen to do exactly that. They use just a few markers to distribute attention ahead of time within the text.

Let me give you an example. Take a look at this natural language first:

We're going on a picnic on July 1st, the destination is xx City's Second Park (Central Park). We'll drive there. You take the ring road from the south side of the city, and I'll drive straight from the north side. We'll meet at 8 AM at Entrance 2 of Second Park. Remember to bring tuna sandwiches, bottled water, and a Bluetooth speaker. I'll bring a picnic blanket, a tent, chicken sandwiches, and mosquito repellent. Also, don't forget to book the park tickets on the app in advance. You can only book one day ahead. Search for xx City's Second Park on the app.

So where are we meeting? You'd have to spend a lot of time digging through the text to find it. But if we switch to a structured description, it's a whole different story:

### Picnic Location
xx City's Second Park

### Meeting Time and Place
- July 1st, meet at 8 AM
- **Entrance 2** of Second Park

### Transportation
- You: Drive via the ring road
- Me: Drive straight from the north side

### Items to Bring
- You: **Tuna** sandwiches, bottled water, Bluetooth speaker
- Me: **Chicken** sandwiches, picnic blanket, tent, mosquito repellent

### Special Notes
- Must book tickets on the app in advance, search for *xx City's Second Park*
- **Can only book one day ahead**

See? After writing it this way, if I ask you which entrance we're meeting at, your search efficiency goes way up, right?

By categorizing and highlighting key points, the important information grabs your attention early on, instead of getting lost in a sea of text.

I wrote a full article explaining my take on structured prompts in plain language. If you're interested, feel free to click and read on.

Don't wait for a multimodal DeepSeek-v4 model, you can use my plugin now to read images.

Peng Qian — Mon, 15 Jun 2026 06:18:01 +0000

Peng Qian

Jun 15

DeepSeek-V4 Can't Read Images? I Made It Read

#ai #programming #coding #vibecoding

4 min read

DeepSeek-V4 Can't Read Images? I Made It Read

Peng Qian — Mon, 15 Jun 2026 06:15:41 +0000

Don't wait for a multimodal model, you can use it now

Introduction

Have you ever had that frustrating moment: you are coding with deepseek-v4 in OpenCode, your code throws an error, you want to screenshot it and send it to DeepSeek, and then you remember that DeepSeek cannot read images.

I have to say deepseek-v4 is cheap, easy to use, and has a long context. It has already become my main coding model. But as of mid-June, DeepSeek still hasn't released a multimodal version. That means anything involving images, like reading error screenshots, interpreting charts, or recreating pages from visual designs, it cannot do.

I am not the only one frustrated. My friends are all waiting eagerly too.

But I found a way: I developed a small plugin called observer in OpenCode that lets deepseek-v4 call a multimodal agent to gain the ability to read images indirectly.

After more than a month of polishing, this plugin now handles all image-related coding tasks in my daily work. Today, I will share how I built this plugin, hoping it can help you too.

The plugin code and agent definitions mentioned in this article are at the end. Feel free to grab them.

Demo of Real-World Results

Before diving into the long tutorial, you probably care most about how well this plugin works and whether it is worth your time to try. So let me show you some screenshots of the plugin in action.

1. Interpreting error stack traces

We start with the simplest task: have deepseek-v4 interpret a screenshot of an error stack trace and find key information. I randomly picked a screenshot of an error I encountered at work:

Then in OpenCode Desktop, I sent this image to the plan agent using deepseek-v4-pro and asked it to provide a solution:

As you can see, the plan agent gave an answer based on the screenshot information.

2. Interpreting charts

Another multimodal use case is interpreting charts from documents. For this example, I took a screenshot of a company's annual revenue chart and tested it. I still used the plan agent with deepseek-v4-pro. For an extra challenge, I asked the agent to give some key insights on the numbers in the chart:

The agent read the numbers from the chart and provided some key insights:

3. Developing HTML pages from designs

In frontend development, the biggest demand for multimodal capability is recreating visual designs. Here I found a design with complex page elements to see if the build agent using deepseek-v4-flash could recreate the page:

Here is the recreated page:

One thing is sure: the deepseek-v4-flash model generated the frontend code, and it only took one prompt to get this result. It did not get a 100% match, but with a few more rounds of conversation, you can tweak it until it is perfect. Keep in mind deepseek-v4-flash is dirt cheap.

It costs several times or even ten times less than multimodal models like kimi k2.6 or qwen3.7 plus. They are not in the same league.

Of course, you can also crop a section of the page, mark the areas that need attention, and ask DeepSeek to adjust them, like this:

The agent perceives the marked area and gives the primary agent an adjustment plan per your request.

4. Generating HTML pages from hand-drawn sketches

Maybe you are like me and have zero design skills. No problem. We can hand-draw rough sketches. The agent can understand them. For example, in a recent project, I hand-drew a few web page design sketches:

Then deepseek-v4-flash helped me recreate the page:

Impressive, right?

Detailed Implementation Walkthrough

Next, you'll find out:

How I designed this plugin and agent.
Why I designed it that way.

Click on my full article to keep reading.

Your AI always writes messy code? That's because your spec files have never been properly reviewed. By adding a reflection mechanism to the proposal stage of OpenSpec, I got DeepSeek-v4-pro to match Opus 4.6 in coding ability:

Peng Qian — Mon, 01 Jun 2026 04:05:05 +0000

Peng Qian

Jun 1

Reflection SDD: Use a Reflection Harness to Level Up Your OpenSpec Workflow

#ai #programming #coding #vibecoding

9 min read

Reflection SDD: Use a Reflection Harness to Level Up Your OpenSpec Workflow

Peng Qian — Mon, 01 Jun 2026 04:00:07 +0000

Stop letting bad spec files tank your code quality

Introduction

In this article, I want to walk you through how I introduced a reflection mechanism into the OpenSpec workflow inside OpenCode, and how that dramatically improved the quality of AI-generated code.

After nearly a month of testing, this reflection workflow has gotten DeepSeek-V4-pro in OpenCode to perform at roughly the same level as Claude Opus 4.6. The only cost is some extra review time and a few more tokens. Trust me, it's worth it.

Can't wait to find out how? Let's get into it.

Why This Works

I've been using AI coding for a while now. Compared to Claude Code, I prefer building my own SDD-based coding workflow with OpenCode and OpenSpec. I wrote a well-received article specifically about this OpenCode workflow:

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

With OpenSpec, and the explore → propose → apply → verify → archive workflow loop, we can finally get LLMs to handle complex project development.

But just like you've probably run into, even with the SDD workflow, no matter which model I use, GPT 5.5 or the latest DeepSeek-V4-pro, the AI still inevitably produces hidden bugs or piles up messy code. Code I'd never feel comfortable putting in production.

My first fix was to call a @reviewer sub-agent after the /opsx-apply phase to do a code review on the changes. Sometimes that worked and caught architectural or implementation issues. But the impact was limited.

Often I'd only discover something was wrong after using the project for a while: a scenario wasn't covered, edge cases were missed, or one part of the code got updated but a related module didn't.

Later I stepped back and looked at the whole AI coding workflow again, and that's when I spotted the real problem.

As programmers, we always focus on whether our code is good, so we naturally look at things from the code level.

But we completely overlooked the quality of the proposal files that OpenSpec generates. We'd finish discussing requirements, generate the proposal file, and then just let the AI start implementing. That's how input-level bugs get introduced. When things go wrong, we blame the model.

Think about it, back in the traditional coding era, when a product manager handed over a requirements doc, there was a critical step before we started coding: requirements review. We wouldn't touch the keyboard until every issue in the requirements doc or design doc was sorted out.

So why did we forget this step in the AI coding era? That's exactly what we're going to fix today: add the requirements review step back into the OpenSpec workflow and see if it makes AI-generated code better.

How to Do It

The SDD workflow isn't anything exotic. If you're familiar with multi-agent system design patterns, you'll recognize that SDD is basically the plan-execute pattern.

One agent breaks the user's task into a step-by-step plan file, then another agent follows that plan to execute the task. This lets the agent system handle complex work.

But how do you guarantee the quality of what the agents produce in a plan-execute setup? That's where a pattern called reflection comes in.

The reflection pattern adds a reflection agent to the multi-agent workflow. This agent typically runs on a completely different LLM and reviews the output of the plan or executor agent from a different angle, which raises the overall performance of the multi-agent system.

The reflection pattern sees wide use in content creation and deep research scenarios, which proves it works.

Since the pattern is proven, we can bring the same reflection step into the OpenSpec workflow, targeting the proposal files.

I'll introduce a reflection agent that runs on a different LLM from the primary agent, reviewing the proposal files from a different angle. We'll also adjust the OpenSpec workflow so this reflection agent plays an active role in it.

Introducing the reflection agent

Adding a new agent in OpenCode is simple. Just drop a new Markdown file into ~/.config/opencode/agents/ with the agent's prompt inside.

The core job of this agent is straightforward: review the artifact files that OpenSpec generates from multiple angles, making sure the quality of the requirements input is solid from the start. This agent sits between the /opsx-propose and /opsx-apply phases.

We can have deepseek-v4-pro generate the first draft of this agent's prompt:

You are an **OpenSpec Change Reviewer** — a critical thinker and auditor focused on substance.

Your job is to review every artifact in an OpenSpec change before it moves to implementation, and find the issues that would actually cause implementation failure or rework.

## Core Principle: Distinguish Substantive Defects from Formatting Issues

**Substantive defects = issues that cause the implementation to go in the wrong direction, miss critical scenarios, create contradictions, or make acceptance impossible.**
**Formatting issues = style or wording differences that don't affect implementation quality.**

Your primary job is to find the former. You can mention the latter, but mark them as optional suggestions and put them at the end.


## Your Position

You work in the **phase between `/opsx-propose` and `/opsx-apply`**:

explore → /opsx-propose → ⬅ you are here (possibly multiple rounds) → /opsx-apply → verify → archive


The spec is not yet frozen. Implementation has not started. Your mission: **find the defects that would actually cause rework or incidents before any code gets written**. Catching a spec error takes minutes. Fixing wrong code takes hours.

## Principles

- **Constructive and strict.** For every issue, explain not just "what" but "why it would cause rework or an incident."
- **Specific, not vague.** Point to exact file locations, requirement names, and task numbers.
- **Severity levels.** 🔴 Blocking vs 🟡 Should Fix vs 💡 Suggestion — don't mix them up.
- **Context-aware.** Evaluate against the existing system (`openspec/specs/`) rather than in a vacuum.
- **Read-only.** Never modify files. You surface problems; OpenSpec executes the fixes.

## Anti-Patterns to Avoid

- Rubber-stamping: saying "looks good!" without deep review.
- Nitpicking: focusing on formatting while missing architectural flaws.
- Jumping to solutions: proposing fixes before the user acknowledges the problem exists.
- Ignoring existing specs: reviewing incremental changes without understanding the baseline.
- Vague feedback: "this could be better" — say exactly what and why.

To review proposals from a different angle and improve the reflection quality, I recommend using a different LLM for the reflection agent than the one the main agent uses. For example, my primary coding agent uses deepseek-v4-pro, so the reflection agent uses kimi k2.6.

---
description: OpenSpec Change Reviewer — after propose and before apply, critically reviews all artifact files under the change (proposal/design/specs/tasks)
mode: subagent
model: kimi-for-coding/k2p6
tools:
    write: false
    edit: false
    bash: false
---

Locking down the openSpec workflow

OpenSpec doesn't actually have a fixed workflow design, users follow a default SDD best practice. So the first step is to lock this workflow down, making OpenCode write an OpenSpec proposal before writing any code.

---
name: openspec-workflow
description: Mandatory prerequisite for ALL OpenSpec operations — load this BEFORE any openspec-* skill. Use when running /opsx-apply, /opsx-propose, /opsx-verify, /opsx-archive, /opsx-explore, /opsx-sync; running `openspec status`, `openspec list`, `openspec instructions`; reading files under `openspec/changes/`; or doing any OpenSpec stage (propose, apply, verify, archive, explore, sync).
license: MIT
compatibility: Requires openspec CLI.
metadata:
    author: Peng Qian
    version: "1.0"
---

## OpenSpec Workflow (Mandatory)

**All code changes must have a proposal before any code gets written.**

### Process
1. **Explore** - When the user says "think about it," "discuss," or "explore," discuss only — no coding.
2. **Propose** - Create proposal files under `openspec/changes/<change-name>/`.
3. **Apply** - Implement according to the proposal tasks. **No file modifications without a proposal.**
4. **Verify** - Verify after implementation is complete.
5. **Archive** - Archive the change.

### Hard Rules

- **Bug fixes don't require editing or creating a proposal.** This hard rule only applies to feature changes or new features.
- **No proposal, no change:** If the user asks to modify code, confirm that a matching proposal exists first, or create one.
- **No proposal, no edits:** Before editing a file, check that a matching change directory exists under `openspec/changes/`.
- **No coding in Explore mode:** When the user is in explore mode, **do not** create proposals, **do not** edit files, **do not** write tests.
- **After a change is complete:** Run the verify process to check that the implementation matches the proposal.

### Proposal Creation Requirements

Every change must include:
- `proposal.md` - reason and scope of the change
- `design.md` - design plan
- `tasks.md` - specific task list
- `.openspec.yaml` - change metadata

Additional requirements:
- **Task granularity:** Each task in `tasks.md` should take no more than 2 hours.

### Violation Handling

Stop immediately and alert the user if any of the following are detected:
- Code modification starts without a proposal.
- Files are edited in explore mode.
- Files outside the current proposal's scope are modified.

You can put this workflow into your project's AGENTS.md file so OpenCode follows it consistently. Or put it in the global ~/.config/opencode/AGENTS.md file so you don't have to configure it for every project.

A better option is to turn the workflow into a skill, so OpenCode only loads this workflow definition when using OpenSpec. I've packaged the full workflow as the openspec-workflow skill, you can grab the source file at the end of the article.

Inserting the reflection agent into the workflow

Once the OpenSpec workflow is locked down as a skill, every SDD coding session will follow the spec-first, code-second process, which means the /opsx-propose and /opsx-apply phases.

As mentioned earlier, the reflection agent sits between these two phases, reviewing the quality of the proposal files before any implementation starts. Following the reflection pattern, this review-and-fix cycle can run for multiple rounds until the proposal artifacts have no serious issues.

To prevent an infinite loop, we need a hard cap on the number of review rounds. Let's update the openspec-workflow SKILL.md file to add the reflection process:

### OpenSpec Reflection Process

1. **After each batch of artifacts is created**, the `@openspec-reviewer` agent **must** be called to review the **artifact files in that batch**.
2. The main agent fixes the **current batch of artifact files** based on the feedback from `@openspec-reviewer`.
3. Call `@openspec-reviewer` again to review the **current batch of artifact files**.
4. **Review pass criteria:**
   4a. **Single-round pass:** After the current review round, if "### 🔴 Remaining Issues" does not exist or is empty, move to the next batch.
   4b. **Fix loop:** If 🔴 issues remain → main agent fixes → next review round → back to 4a. Repeat until passing or 4c triggers.
   4c. **Hard cap (MAX_ROUNDS = 5):** If the same batch has gone through 5 review rounds without passing 4a → stop the loop and hand off to a human for a decision.

At this point, a typical reflection process for OpenSpec proposals is in place. All you need to do is run /opsx-propose, go grab a coffee, and wait for the reflection agent to gradually refine your proposal.

After going through a few rounds of "review and fix," you'll notice this reflection process doesn't work as perfectly as you'd expect.

It's common to fix issue A only to have issue B pop up. Sometimes all 5 review rounds finish, and not every issue is fully resolved. Especially with powerful but not top-tier models like deepseek-v4. It's fine. We can optimize the process to fix this.

So what's next:

I'll require that discussions in the explore phase be saved as files, so the proposal creation and review process has a checklist baseline.
Review one file at a time, rather than waiting for all files to be generated before starting the review.
Save the logs from each round of review, so they can be used in the next round or when someone needs to step in manually.

I've also included the full source files for the reflection agent and the OpenSpec Workflow skill.

Interested? Click here to keep reading.

Ride the wave of AI coding, don't get swept away by it. In my latest article, I dive into the practical details of building your own personal AI coding setup using OpenCode Oh-My-OpenCode-Slim OpenSpec. It will help you get a better handle on AI coding.

Peng Qian — Fri, 17 Apr 2026 12:14:25 +0000

Peng Qian

Apr 17

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

#vibecoding #coding #ai #python

8 min read

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

Peng Qian — Fri, 17 Apr 2026 12:11:48 +0000

Introduction

I have never used Claude Code. The reason is simple. Claude Code is too expensive. Even with a subscription, the cost-to-value ratio does not work for my research.

So I have been building my own AI coding environment using OpenCode as the foundation, combined with Oh-My-OpenCode-Slim (multi-agent orchestration) and OpenSpec (SDD).

My take is this: if you understand what you want to build, and you know how to use coding tools properly, especially with well-written Spec files as constraints, frontier open-source models like Qwen3.6-Plus, Kimi-k2.5, and GLM-5 can handle your daily coding tasks just fine.

There is another huge advantage to open-source software: community power. The community can tune system prompts and model parameters to fit different models well, and get the most out of open-source models.

In this article, I want to share what I have learned from using OpenCode and its surrounding tools. I will skip the generic tutorials you find everywhere online and focus only on the details I think actually matter. I hope this helps you make better choices.

Tool Installation and Environment Setup

I will cover my experience in two parts: installing and configuring OpenCode and its related plugins, and my AI coding workflow.

Let's start with tool installation and environment setup, beginning with OpenCode itself.

Installing OpenCode

Unlike most coding agents that only offer a TUI-based command-line tool, OpenCode also comes with a desktop app with a graphical interface. I use the desktop app for my daily coding work. It is clearly much more efficient than the TUI version.

That said, you still need to install the command-line program first. From my testing, some plugins need a command-line environment to check whether OpenCode is installed on your machine during project initialization.

First, make sure you have Node.js installed. Then run this npm command to install the OpenCode CLI:

npm i -g opencode-ai

After that, go to the official website, download the OpenCode Desktop installer, and double-click to install.

Configuring OpenCode

After installing OpenCode Desktop, open the app. Once you select your project directory, you will land on the main OpenCode interface. The features are fairly intuitive, so I will not walk through each one. But before you type your first Hello World, you should check your terminal configuration first.

Configuring the terminal

I use Windows 11. On Windows, OpenCode Desktop defaults to PowerShell as its terminal. Many companies, though, do not allow PowerShell. If you are in a non-English locale, OpenCode may run into character encoding issues when running shell commands through PowerShell, causing those commands to fail.

In that case, you need to change your default terminal.

OpenCode uses the SHELL environment variable to determine which terminal to use. You can configure Windows Command Prompt (cmd.exe), WSL, or git bash. Personally, I prefer cmd.exe because I had already installed a lot of CLI tools before setting up OpenCode. Using cmd.exe directly saves me from reinstalling everything.

SET SHELL="%windir%\system32\cmd.exe"

Configuring model providers

Next, let's talk about how to configure model providers.

Open the settings window and select "Providers". You will see a list of the most popular model providers and API relays. If you want to use open-source models, though, they probably will not be on that list.

At that point, you might click "Custom provider" and manually fill in the model id, base url, api key, and so on. The problem is that OpenCode then has no idea about your model's context window size or pricing, which causes features like automatic context compression to stop working correctly.

The right approach is to click the "Show more providers" link at the bottom, find the provider you want to add, and enter that provider's api key.

Once configured, all models from that provider will appear in the model list. These models come with metadata like context size and pricing, so context management plugins can work correctly.

The downside is that you cannot directly see your provider ID this way, which makes it tricky to configure Oh-My-OpenCode-Slim later.

No worries. OpenCode already saved your provider configuration when you selected your provider. You can find it at ~/.local/share/opencode/auth.json. Your provider ID and API key are both there.

Enable workspaces

The biggest difference between AI coding and traditional coding is that while you wait for the AI to work, you can actually work on another requirement at the same time. If you use git for version control, you would normally need to create a separate directory and check out a new branch.

Or you can use git's worktree feature to create a new worktree on top of your current branch. When you are doing parallel development, using worktrees is much more convenient than creating new branches.

Compared to OpenCode CLI, the desktop app has a clear advantage here: it natively supports the worktree feature. In OpenCode Desktop, this feature is called "workspace".

The way to open a workspace is a bit hidden. Right-click the project icon in the top-left corner of the window, then select "Enable Workspace" from the menu. From there, you can create multiple workspaces in the conversation list and work on them simultaneously. The corresponding branches and code directories will be created automatically.

When the coding work in a workspace is done, you can ask the AI to submit a PR for the current code, then close the workspace. The branch and code directory that were created for it will be cleaned up automatically. Very convenient.

Choosing the right agent

If you want to use OpenCode without any extra plugins, pay attention to how you use agents.

OpenCode has two types of agents: primary agents, which you choose yourself, and sub-agents, which the primary agent calls on its own when needed.

Without any plugins installed, OpenCode only provides two primary agents: Build and Plan: The Build agent has full tool access and is the default choice. The Plan agent has no editing permissions. Its job is to ask you clarifying questions when you describe a requirement, and eventually produce an execution plan.

When you first try this, you might go straight to the Build agent. But for complex tasks, Build tends to just start coding based on its own interpretation. That is like looking through a straw. It fixes things locally without thinking through the overall architecture and design patterns.

The right approach is to start every new requirement with the Plan agent for requirement clarification, and get a solid execution plan first. Only then should you hand things off to Build to start development.

But even that is not enough. Model context is limited. As coding progresses, the execution plan from earlier in the conversation can get pushed out of the context window.

A better approach is to ask Build to save the execution plan as a Markdown file before starting to code. Review that file, confirm everything looks good, then start a fresh session and have Build load the execution plan document back in before executing.

Once you start working this way, you will feel how much value comes from planning before executing. It also sets you up well for SDD coding later, which I will cover when we get to OpenSpec.

Always start a new session

I just mentioned that after forming a development plan, you should create a new session before continuing with coding. Why?

Because anyone familiar with LLMs knows that even though context windows are long today, and OpenCode does offer context compression, context rot is still a real problem. LLMs pay more attention to the beginning and end of the context window, and less to the middle. I call this positional bias.

So to make sure the LLM follows instructions accurately based on the conversation context, especially after forming an execution plan where you need precise execution, start a new session after each major milestone. Do not keep working in the same session forever.

Do not forget to create AGENTS.md

The AGENTS.md file is called "rules" in OpenCode. You can create it automatically with the /init command. It tells the LLM what rules to follow during coding.

You may ask: if this file is created by the LLM, does that not mean the LLM already knows all these rules internally? Is saving them to a file redundant?

Not at all. AGENTS.md is a file written specifically for the LLM to read. In my view, it serves three important purposes:

First, AGENTS.md acts as long-term memory for the project. It locks in facts and choices. For example, after asking the LLM to set up the project structure or create a new module, run /init once. The project architecture gets locked into AGENTS.md. Without this, the LLM will scan the entire project from scratch every time you start a new session, wasting a huge number of tokens.

Another example: if you use uv to manage your project and use uv sync --prerelease=allow to sync prerelease dependencies, write that clearly in AGENTS.md. This prevents the LLM from making errors with dependency management.

Second, AGENTS.md narrows the probability distribution and reduces hallucinations. LLMs are probability models. When facing a question, an LLM generates several possible answers with associated probabilities, then picks one based on the temperature parameter.

For example, when a method parameter can accept multiple types, the LLM might consider these options:

Use Optional[int] (40% chance)
Use int | None (40% chance)
Use no type annotation at all (20% chance)

At that point, the LLM will randomly pick Optional[int] or int | None.

But once you explicitly require str | None syntax in AGENTS.md, the probability distribution shifts to:

Use int | None (100% chance)
Use Optional[int] (0% chance)

At this point, the LLM will just go ahead and pick int | None as the final answer.

Third, AGENTS.md serves a harness engineering purpose. You can give the LLM direct instructions through AGENTS.md that it must follow. For example, you can tell the LLM to communicate with you in Chinese, or require that during the spec-driven process, it cannot create new proposals without your approval.

Improve the success rate of Skills loading

By now, most people in the AI coding space have heard of Skills. But many find that Skills do not load reliably under normal conditions.

There are two reasons for this. On one hand, the description in a Skill's front matter is often unclear. We need to write the front matter carefully, especially the description part. It should clearly explain when the Skill applies and what it provides, so the LLM can load the right Skill for the situation.

On the other hand, for common coding scenarios, LLMs have learned so much during pretraining that they do not feel the need to load a Skill for extra guidance.

For this, there is a simple and proven fix. Just add this line to AGENTS.md:

Here's what's coming up next:

How to improve the Skills loading success rate.

How to properly configure Oh-My-OpenCode-Slim.

The complete OpenSpec and SDD development workflow.

Visit Data Leads Future to read the full content.

The hardest part of enterprise AI agents is wiring into real workflows. I built a setup where: ✅Agent Skills load in real time from a database ✅Scripts run safely in containers ✅A “skills agent” acts as a tool to keep the main agent’s context clean

Peng Qian — Thu, 19 Mar 2026 10:34:25 +0000

Peng Qian

Mar 19

How to Use Agent Skills in Enterprise LLM Agent Systems

#ai #programming #datascience #tutorial

11 min read

How to Use Agent Skills in Enterprise LLM Agent Systems

Peng Qian — Thu, 19 Mar 2026 10:32:10 +0000

Introduction

Enterprise-grade agentic systems have fallen way behind the desktop agent apps that everyone's been buzzing about lately.

After spending the better part of a year building enterprise agent applications, I came to one conclusion: if your agent system can't plug into your company's existing business processes, it won't bring real value to your organization.

Desktop systems like OpenClaw and Claude Cowork solved this problem. They don't change their agent setup at all. Instead, they use Agent Skills to capture human business processes, then share those skills between desktop agent systems through the file system. That's how they tackle one business problem after another.

But enterprise users write their skills through a web interface and save them to a database. There's a good chance the process involves complex approval and security audit steps, too. So how does your agent load these skills in real time without any downtime?

The latest version of Microsoft Agent Framework finally makes this possible with its Agent Skills feature.

TL;DR

With Agent Skills in Microsoft Agent Framework, enterprise agent systems can load user-defined business process skills from a database in real time, and run the scripts and generated code that come with those skills safely inside containers.

Your agent system stays secure and stable, while gaining the same flexible business process orchestration that desktop agents enjoy.

All the source code in this tutorial is available at the end of the article.

Before We Start

Install the latest Microsoft Agent Framework

To use Agent Skills, install the latest version of Microsoft Agent Framework:

pip install agent-framework --pre

Or, like me, you can pin the version of agent-framework in your pyproject.toml:

dependencies = [
    "agent-framework>=1.0.0rc4",
    "agent-framework-ag-ui>=1.0.0b260311",
]

Then tell uv to allow prerelease versions:

uv sync --prerelease=allow

Install Tavily Agent Skills

My end goal is to show you how to share and load Agent Skills between agents deployed across distributed nodes. But I think we should start simple. First, let me show you how to load and use skills from the community.

Let's start with Tavily Agent Skills. We'll only load the tavily-best-practices skill. It guides my agent on how to generate Tavily-based search code based on the task at hand, instead of calling a hardcoded function:

npx skills add tavily-ai/skills

Don't worry. After the initial demo, I'll walk you through how to load skills from a database in real time.

How to Load Agent Skills from Disk

Let's start with the most basic approach.

In Microsoft Agent Framework, context operations are handled by a base class called ContextProvider. The latest version of MAF ships a SkillsProvider class. Use it directly and pass the location of your skills through the skill_paths attribute, and you're done. skill_paths doesn't require a default directory like .claude/skills, and you can pass in multiple paths.

skills_provider = SkillsProvider(
    skill_paths=get_current_directory() / ".agents/skills",
)

Next, create your agent and pass the skills_provider instance through context_providers.

skills_agent = chat_client.as_agent(
    name="SkillsAssistant",
    instructions="You're a helpful assistant, and you'll respond to user requests according to your skills.",
    context_providers=[skills_provider],
    tools=[code_tool],
)

To run the Python code the agent writes based on the Tavily skill instructions, you need to pass a code_interpreter tool to the agent. Let the code run inside a container environment. I'll cover that in detail later.

Write a main method to test the agent:

async def main():
    async with code_executor:
        session = agent.create_session()
        result = await skills_agent.run(
            "Check how gold ETFs performed in February 2026 and give some investment advice.",
            session=session
        )

        print(result)

Microsoft Agent Framework provides an OpenTelemetry-based telemetry tool. I hooked it up to MLflow. Let's run the agent once and see what happens:

You can see that once the agent decided it needed Tavily to search, it loaded the full SKILL.md document, wrote Tavily search code following the instructions, then sent it to the code interpreter for execution. Exactly what we expected.

You can learn how to use MLFlow in this article:

Monitoring Qwen 3 Agents with MLflow 3.x: End-to-End Tracing Tutorial

How Agent Skills Work

Now let's talk about how to get the most out of Agent Skills in enterprise systems. That means loading external skills in real time, containerizing the code interpreter, and managing context more carefully.

But before we go there, let's dig into how Agent Skills actually work inside MAF, so the rest of this tutorial makes more sense.

As I mentioned, SkillsProvider extends BaseContextProvider, which means it works by operating on the agent's context.

When you initialize SkillsProvider, you pass one or more search paths to the skill_paths attribute. Take the .agents/skills directory as an example. On startup, SkillsProvider recursively searches this directory and finds every subdirectory that contains a SKILL.md file. Then it extracts the name and description fields from each SKILL.md file, along with the file content, and stores everything in a Skill object.

SkillsProvider loops through these Skill objects, formats the name and description fields like this, and merges them into the agent's system prompt. This keeps the agent aware of available skills without loading their full content upfront.

lines.append("  <skill>")
lines.append(f"    <name>{xml_escape(skill.name)}</name>")
lines.append(f"    <description>{xml_escape(skill.description)}</description>")
lines.append("  </skill>")

SkillsProvider also adds two methods to the agent through context: load_skill and read_skill_resource. When the agent decides which skill it needs based on the user's request, it calls load_skill to look up the matching Skill object by name and loads its full content into the context.

If a skill's content references extra resource files like references/search.md, the agent can call read_skill_resource to load those files.

Here's the full workflow:

This design follows the progressive disclosure principle defined by agentskills.io. Skill content loads into the agent's context gradually, only when needed. No context explosion, no wasted tokens.

Agent Skills for Enterprise Systems

Alright, enough theory. Let's get into today's main topic: how to use Agent Skills in enterprise-grade agentic systems.

Load skills from external systems in real time

What if business users write their skills through a cloud-based web page and save them to a database? How do you handle that?

We need a new approach to sync and apply Agent Skills in real time.

As I covered earlier, when SkillsProvider initializes, it loads all SKILL.md files from the input paths into an in-memory list of Skill objects.

Besides the file system approach, SkillsProvider also supports Code Defined Skills, where you write skill content directly in code:

from pathlib import Path
from agent_framework import Skill, SkillsProvider

my_skill = Skill(
    name="my-code-skill",
    description="A code-defined skill",
    content="Instructions for the skill.",
)

Then pass it to SkillsProvider through the skills attribute:

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    skills=[my_skill],
)

This opens the door to managing and loading skills from a database. But the original SkillsProvider class only accepts skills at initialization time. We want to load skills dynamically while the agent system is running, so we need to extend SkillsProvider.

After reading the source code, I found that every class extending BaseContextProvider has a before_run method that gets called when the agent calls run. We can load the latest skills from the database before before_run executes, then update SkillsProvider's self._skills list and refresh the skills description in instructions.

What I need is a hook method. Every time before before_run runs, this hook fetches the latest skills. All I need to do is put the database fetching logic inside this hook.

The simplest way to give SkillsProvider this hook is to build an UpdatableSkillsProvider subclass. This subclass accepts a skills_updater parameter at initialization:

class UpdatableSkillsProvider(SkillsProvider):
    def __init__(
        self,
        skill_paths: str | Path | Sequence[str | Path] | None = None,
        *,
        skills_updater: Callable[[], Awaitable[Sequence[Skill]]] | None = None,
        **kwargs
    ):
        super().__init__(
            skill_paths=skill_paths,
            **kwargs,
        )
        self._skills_updater = skills_updater
        ...

UpdatableSkillsProvider calls the hook through a private _update method, which also updates self._skills and the agent's system prompt. Then before_run calls _update to keep skills fresh in real time:

class UpdatableSkillsProvider(SkillsProvider):
    ...
    async def _update(self) -> None:
        if self._skills_updater is None:
            return

        try:
            new_skills = await self._skills_updater()

            for skill in new_skills:
                self._skills[skill.name] = skill

            has_scripts = any(s.scripts for s in self._skills.values())

            self._instructions = _create_instructions(
                prompt_template=self._instruction_template,
                skills=self._skills,
                include_script_runner_instructions=has_scripts,
            )

            self._tools = self._create_tools(
                include_script_runner_tool=has_scripts,
                require_script_approval=self._require_script_approval,
            )

        except Exception as exc:
            logger.exception("Failed to update skills: %s", exc)

    @override
    async def before_run(
        self,
        *,
        **kwargs
    ) -> None:
        await self._update()
        await super().before_run(
            **kwargs
        )

Let's write a get_latest_skills hook to simulate loading the latest skills from a database:

@lru_cache
async def get_latest_skills() -> list[Skill]:
    """
    Pseudocode. In this hook method, you can read the skills text from the database 
    and dynamically build Skill objects.
    :return: 
    """
    code_style_skill = Skill(
        name="code-style",
        description="Coding style guidelines and conventions for the team",
        content=dedent("""\
            Use this skill when answering questions about coding style,
            conventions, or best practices for the team.
        """),
    )

    return [code_style_skill]

Call the agent's run method, then check in MLFlow whether the skills loaded by get_latest_skills show up in the agent's system prompt:

The hook method works. We can now load skills from a database in real time.

Run scripts from skills safely inside containers

As of the latest version, Microsoft Agent Framework can't run Python scripts locally or inside containers. But most skills guide the agent through business logic using scripts, so we need to give the agent the ability to run those scripts in a code interpreter.

As the predecessor to MAF, Autogen provided a way to run Python scripts inside Docker containers. You can learn about that in this article:

Exclusive Reveal: Code Sandbox Tech Behind Manus and Claude Agent Skills

We need something like Autogen's DockerCommandLineCodeExecutor for Agent Framework. With the help of AI coding tools, building a code executor for Agent Framework isn't hard. (You can find it in the source code repo at the end of the article.)

code_executor = DockerCommandLineCodeExecutor(
    image="python-code-sandbox",
    work_dir=work_dir,
    delete_tmp_files=True,
    environment={
        "TAVILY_API_KEY": os.environ.get("TAVILY_API_KEY"),
    }
)

To keep LLM calls simple, we also need an object-oriented CodeExecutionTool:

class CodeExecutionTool:
    """Tool for executing code using a CodeExecutor."""

    def __init__(self, executor: CodeExecutor) -> None:
        self._executor = executor
    async def execute_code(self, code: str, language: Literal["python", "sh"] = "python") -> str:
        result = await self._executor.execute_code_blocks(
            [CodeBlock(code=code, language=language)],
            CancellationToken(),
        )
        return result.output

Next, initialize an execute_code tool and wire it up to the agent at initialization:

code_tool = CodeExecutionTool(code_executor).execute_code

In MLflow, you can see that when the agent needs to search the web, it generates Python code based on the skill's instructions and sends it to the container for execution:

This approach not only lets the agent run code defined in skills, but also keeps that execution safe inside a container.

Of course, in a server-side deployment, you'd send code to a centralized Jupyter kernel environment for execution. But that's a whole other story. You can dig into that in my other articles.

How I Crushed Advent of Code And Solved Hard Problems Using Autogen Jupyter Executor and Qwen3

Reduce context length even further

Agent Skills uses progressive disclosure to keep irrelevant skill content from eating up your context window. But as the conversation or task moves forward, skill content that was loaded into earlier messages will still pile up in the context over time.

Agent systems today have several context pruning techniques available. Context trimming and context compression, both common in desktop agents, work really well.

Beyond those two, today I want to share a context engineering technique I discovered at work that fits Agent Skills even better.

As you know, in enterprise scenarios, loading a skill usually means running one atomic workflow: researching a topic through web search? Sure. Running a SWOT analysis on a company and writing a report? No problem.

These workflows all share one thing in common. You give the agent the right input, then wait for it to return an output. Which skill the agent loaded, and how it worked through the task — I honestly don't care. I wouldn't even mind if the agent unloaded the skill after finishing to save tokens.

That sounds a lot like how a function works. So, can we use an agent with skills loaded as a tool for another agent? Absolutely. That's exactly what I do.

Microsoft Agent Framework has a method on Agent called as_tool. It turns an agent into a function-callable tool.

So I designed a main agent. The main agent takes user requests and generates the right response to return. The agent with Agent Skills loading capability turns itself into a tool for the main agent using as_tool.

agent = chat_client.as_agent(
    name="Assistant",
    instructions=dedent("""
    You're a smart little helper who, for each user request, 
    picks the right task description to call a tool, gets the answer, 
    and then delivers the final result.
    """),
    tools=[skills_agent.as_tool()],
)

The skills agent's workflow stays the same. It loads the right skill based on the task description, generates and runs code, then returns the result.

But the main agent is different. Its context only holds user messages, the message calling the skills agent tool, and the final response. No skill-related content at all. The main agent's context stays clean, and even after running for a long time, it won't interfere with the LLM.

There's a nice bonus too. LLMs know what they want better than humans do, so before the main agent calls the skills agent, it rewrites the user's task into something more precise. This helps the skills agent execute more accurately.

Conclusion

That's everything I have for you today on Agent Skills for enterprise agent systems.

Unlike desktop agents, enterprise agent systems run on cloud servers. There's no way to update an agent's skills through the file system in real time without downtime.

So I went with a targeted approach. This approach lets users write skill content through a web interface and save it to a database, while agents read the latest skills in real time and sync them across server nodes.

I used the latest version of Microsoft Agent Framework to build this, but you can use any other framework. The principles are the same.

I also covered how to run scripts the agent generates from skills inside containers, which is much safer than running scripts directly on a desktop system.

I shared a context management approach I found at work that works especially well for skills-based agents.

The Microsoft Agent Framework API is still a bit unstable. If anything is unclear, feel free to leave a comment, and I'll get back to you as soon as I can.

Thanks for reading! Share this with your friends if you think it might help someone else.

Enjoyed this read? Subscribe now to get more cutting-edge data science tips straight to your inbox! Your feedback and questions are welcome — let’s discuss in the comments below!

This article was originally published on Data Leads Future.

DEV Community: Peng Qian

The concept of Loop Engineering has been getting a lot of buzz lately, so I decided to give it a shot in OpenCode. The results were surprisingly good:

How I Built a Fully Automated Coding Loop in OpenCode

How I Built a Fully Automated Coding Loop in OpenCode

Introduction

What Andrew Ng Says About the Coding Loop

My Attempts

1. Write a Fibonacci script

2. Build a Tower of Hanoi web game

3. Build a chess web game

4. A typing practice game for kids

Pretty cool, right? Feeling curious?

Further Reading

The essence of prompt engineering isn't about feeding the model more information. It's about helping both the model and humans put their limited attention in the right place.

Why Well-Written Prompts Are Almost Always Structured

Why Well-Written Prompts Are Almost Always Structured

Don't wait for a multimodal DeepSeek-v4 model, you can use my plugin now to read images.

DeepSeek-V4 Can't Read Images? I Made It Read

DeepSeek-V4 Can't Read Images? I Made It Read

Introduction

Demo of Real-World Results

1. Interpreting error stack traces

2. Interpreting charts

3. Developing HTML pages from designs

4. Generating HTML pages from hand-drawn sketches

Detailed Implementation Walkthrough

Your AI always writes messy code? That's because your spec files have never been properly reviewed. By adding a reflection mechanism to the proposal stage of OpenSpec, I got DeepSeek-v4-pro to match Opus 4.6 in coding ability:

Reflection SDD: Use a Reflection Harness to Level Up Your OpenSpec Workflow

Reflection SDD: Use a Reflection Harness to Level Up Your OpenSpec Workflow

Introduction

Why This Works

How to Do It

Introducing the reflection agent

Locking down the openSpec workflow

Inserting the reflection agent into the workflow

So what's next:

Ride the wave of AI coding, don't get swept away by it. In my latest article, I dive into the practical details of building your own personal AI coding setup using OpenCode Oh-My-OpenCode-Slim OpenSpec. It will help you get a better handle on AI coding.

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

Introduction

Tool Installation and Environment Setup

Installing OpenCode

Configuring OpenCode

Configuring the terminal

Configuring model providers

Enable workspaces

Choosing the right agent

Always start a new session

Do not forget to create AGENTS.md

Improve the success rate of Skills loading

Here's what's coming up next:

The hardest part of enterprise AI agents is wiring into real workflows. I built a setup where: ✅Agent Skills load in real time from a database ✅Scripts run safely in containers ✅A “skills agent” acts as a tool to keep the main agent’s context clean

How to Use Agent Skills in Enterprise LLM Agent Systems

How to Use Agent Skills in Enterprise LLM Agent Systems

Introduction

TL;DR

Before We Start

Install the latest Microsoft Agent Framework

Install Tavily Agent Skills

How to Load Agent Skills from Disk

How Agent Skills Work

Agent Skills for Enterprise Systems

Load skills from external systems in real time

Run scripts from skills safely inside containers

Reduce context length even further

Conclusion