The 30-Minute Self-Improving Agent Starter Kit

Why a starter kit?

The first version of a self-improving agent should be boring. That is a compliment.

Most people do not need a model that trains itself. They need an agent that stops repeating the same mistakes: editing the wrong file, skipping validation, forgetting a project rule, turning a one-time preference into a permanent rule, or making a risky change without asking.

This starter kit is the smallest working version of that loop. It does not require a new framework. It starts with a folder and five files.

/agent-system
  /tasks
    current-task.md
  /sop
    project-sop.md
    risk-policy.md
  /logs
    self-improvement-log.md
  /evals
    task-checklist.md
    post-task-reflection.md
  /skills
    skill-candidate-proposal.md

The point is not the directory tree. The point is the decision rule behind it:

The loop

Use the same loop after every meaningful task:

That is the practical version of self-improvement. The model may be the same tomorrow. The working environment is not.

1. Create the task file

Create this file:

/tasks/current-task.md

Use this template:

# Current task

date:
owner:
status: planned | in_progress | blocked | done

## Goal

What are we trying to accomplish?

## Context

What should the agent know before starting?

## Files or tools involved

-
-
-

## Constraints

-
-
-

## Done means

- [ ]
- [ ]
- [ ]

## Validation

How will we know the result is correct?

- [ ] Test passed
- [ ] Links checked
- [ ] User reviewed
- [ ] Output matches template
- [ ] No known safety issue

Many agent failures happen before the first edit. The agent starts acting before the task has a clear finish line. A task file forces the user and the agent to agree on what done means.

2. Create the project SOP

Create:

/sop/project-sop.md

Use this template:

# Project SOP

## Purpose

This file contains stable rules the agent should follow in this project.

## Default workflow

1. Read the current task file.
2. Read relevant SOP files.
3. Inspect existing files before editing.
4. Make the smallest safe change.
5. Validate the result.
6. Summarize what changed.
7. Write a reflection if something reusable was learned.

## File rules

- Do not overwrite long documents with summaries.
- Do not use placeholders such as "original content preserved."
- Read before writing.
- Read back after writing.
- When unsure, inspect the directory before choosing a file.

## Quality rules

- Prefer specific facts over generic claims.
- Separate facts, user preferences, and agent judgment.
- Do not turn one-time feedback into permanent policy.
- Use checklists for repeated mistakes.

## Safety rules

The agent must ask for approval before:

- deleting files
- changing global rules
- changing deployment steps
- adding permissions
- using secrets or credentials
- running destructive operations
- creating automation that acts without review

This is where most users get leverage. A project SOP is cheap, readable, and available to the next chat. It turns hidden expectations into something the agent can load.

3. Create the self-improvement log

Create:

/logs/self-improvement-log.md

Use this template:

# Self-improvement log

Use this file to record lessons from completed tasks.

## YYYY-MM-DD - Short title

task:

result:

validation:

what_worked:

what_failed:

user_correction:

root_cause:

lesson:

new_rule_candidate:

category: rule | preference | pattern | bug | observation

risk_level: low | medium | high

write_to: log | SOP | template | script | skill | global rule

action_taken:

status: proposed | written | rejected | deferred

follow_up_needed:

A weak log says, “Task completed successfully.” A useful log says, “The agent initially edited a generated file instead of the source file. Root cause: the SOP did not identify the true source directory. New rule: before editing a generated page, inspect the build pipeline and find the source.”

That second log entry makes the next task safer.

4. Create the task checklist

Create:

/evals/task-checklist.md

Use this template:

# Task checklist

Before starting:

- [ ] Did I read the task file?
- [ ] Did I read the relevant SOP?
- [ ] Do I know what "done" means?
- [ ] Do I know which files are source files and which are generated?
- [ ] Do I know what requires human approval?

Before writing files:

- [ ] Did I inspect the existing file?
- [ ] Am I editing the true source?
- [ ] Am I making the smallest safe change?
- [ ] Am I preserving existing content?
- [ ] Am I avoiding placeholder text?

Before finishing:

- [ ] Did I validate the result?
- [ ] Did I read back the changed section?
- [ ] Did I report what changed?
- [ ] Did I mention anything not completed?
- [ ] Did I check whether this task produced a reusable lesson?

Self-improvement check:

- [ ] Did a repeated mistake appear?
- [ ] Did the user correct the agent?
- [ ] Did the workflow become clearer?
- [ ] Should this become a log entry?
- [ ] Should this become an SOP rule?
- [ ] Should this become a skill candidate?
- [ ] Is the change high-risk and waiting for approval?

This is the cheapest evaluation layer. Many users think they need a full observability platform before they can improve an agent. They do not. A checklist catches plenty of failures before they become expensive.

5. Create the post-task reflection template

Create:

/evals/post-task-reflection.md

Use this template:

# Post-task reflection

## Task

What was the task?

## Result

What changed?

## Validation

How was the result checked?

## What worked

What should be repeated next time?

## What failed

What went wrong or almost went wrong?

## User correction

Did the user correct the agent? What exactly did they correct?

## Root cause

Why did the mistake happen?

## Lesson

What is the reusable lesson?

## Category

Choose one:

- rule
- preference
- pattern
- bug
- observation

## Risk level

Choose one:

- low
- medium
- high

## Recommended action

Choose one:

- write to log only
- update project SOP
- create template
- create script
- propose new skill
- propose global rule change
- no action

## Approval needed?

Yes / No

Reason:

Use this after meaningful work, not after every tiny request. The goal is not paperwork. The goal is to catch the moments where the agent learned something that should survive the current chat.

6. Create the skill candidate proposal

Create:

/skills/skill-candidate-proposal.md

Use this template:

# Skill candidate proposal

## Trigger

When should this skill be used?

## Repeated task

What task has appeared more than once?

## Why SOP is not enough

Why does this need a reusable workflow instead of one rule?

## Workflow steps

1.
2.
3.
4.
5.

## Required files

-
-
-

## Tools used

-
-
-

## Validation

How should the agent know the workflow succeeded?

- [ ]
- [ ]
- [ ]

## Risk level

low | medium | high

## Suggested skill name

## Suggested skill path

## Should create now?

yes | no

## Possible downside

What could go wrong if this becomes a skill?

A skill should not be created after one lucky task. Create a skill when the workflow is repeated, multi-step, clear enough to document, and easy to validate.

7. Create the risk policy

Create:

/sop/risk-policy.md

Use this template:

# Risk policy

## Low-risk changes

The agent may write these directly and report them afterward:

- task log entries
- typo fixes in local notes
- project-specific checklist additions
- low-impact SOP clarifications
- formatting templates
- non-destructive documentation updates

## Medium-risk changes

The agent should explain before writing, or write only when the user clearly requested it:

- project SOP changes
- new project-level skills
- changes to publishing workflow
- changes to validation steps
- changes that affect multiple future tasks in one project

## High-risk changes

The agent must ask for approval first:

- global agent rules
- cross-project rules
- permission changes
- shell/tool access changes
- deployment automation
- deletion or destructive edits
- secrets, tokens, credentials
- automatic commit, push, publish, payment, or email
- rules that allow the agent to approve itself

This file is the difference between useful self-improvement and unsafe self-modification. A good system lets the agent suggest better rules. It does not let the agent silently expand its own power.

How to map this to common agents

The folder kit is neutral. Each agent has its own natural place for rules, skills, and approval.

These mappings are not theoretical. Anthropic’s skills repository describes skills as folders of instructions, scripts, and resources. Claude Code subagents can include custom prompts, tool restrictions, permission modes, hooks, and skills. OpenClaw’s workspace docs tell users to treat the workspace as memory, and its skill docs describe SKILL.md folders. Cursor documents User, Project, and Team Rules, plus Agent Skills. Codex documents global and repo-level AGENTS.md, and its Skills docs use the same SKILL.md packaging idea. AIAnthropic Skills↗OCOpenClaw workspace↗CUCursor Rules↗OCodex AGENTS.md↗

The 30-minute setup plan

At the end of thirty minutes, the model is not smarter. The system is easier to improve.

A copyable first instruction

Give this to your agent at the start of a project:

Use this project as a self-improving workflow.

Before starting:
1. Read /tasks/current-task.md.
2. Read /sop/project-sop.md.
3. Read /evals/task-checklist.md.

During the task:
1. Make the smallest safe change.
2. Preserve existing content unless explicitly asked to replace it.
3. Validate the result before finishing.

After the task:
1. Summarize what changed.
2. Explain how it was validated.
3. Identify any mistake, user correction, or reusable pattern.
4. Decide whether the lesson belongs in log, SOP, template, script, or skill.
5. Ask for approval before high-risk rule changes.

This one instruction creates the loop.

What not to automate first

Do not automate these at the beginning:

Self-improvement should make the agent safer and more predictable. If the system becomes harder to inspect, it is moving in the wrong direction.

The final test

The starter kit is working if these statements become true:

That last point matters most. If the improvement only exists in one chat window, the system did not improve. The conversation did.

Further reading

Three sources to read next. Each card links to the original source; the thumbnails are AI Picker editorial covers, not publisher images.

aipicker.xyz Self-Improving Agents for Normal People Companion note openai.com Codex Skills: package repeated work into SKILL.md folders Docs openai.com Codex best practices: make guidance reusable Docs