Definition: session context

Starting a new chat session, with any LLM, begins with no knowledge of previous conversations and work done so far. As you type the first instruction, AGENTS.md (or CLAUDE.md) is loaded first. This is known as the system prompt. Its purpose is to hold the session instructions which the agent is going (to try) to follow strictly.

The knowledge and decisions made within the current conversation are what we call session context. Once the context grows too large (currently around the 200k token mark, although many bigger LLMs now support a context window of up to 1M tokens), the agent will force a compaction - it will create a summary of the conversation so far and replace the context with it. When this happens, the system prompt is going to be reloaded. This guarantees that a fresh, full-text copy of its instructions exists in the new context.

Add this at the end of AGENTS.md, if you want to see when it’s loaded:

# Sanity check
AGENTS.md loaded

System prompt priority

System prompts are treated differently: they have higher priority than your other text messages, which are known as user prompts. Designing them carefully is very important, as your agent will do its very best to follow the instructions in them strictly.

Not having an AGENTS.md (or CLAUDE.md) is going to cause more agentic drift. Because LLM responses to the same prompt are non-deterministic (i.e. the output is different every time for the same question), we use the system prompts to constrain that behaviour. This is our “first line of defence” against hallucinations and sporadic behaviour.

Typical structure of a system prompt

There are numerous things that people put in their system prompt. Here I’m going to outline the general sections that apply in principle to most projects:

• Purpose: this is the top-level description of the project/codebase (e.g. Project Overview).
• Skills: a reference to existing skills. The agent might read their descriptions on start, but it might not do it after compaction, so keeping a short index here helps, especially when you have skills that are supposed to be auto-loaded.
• Workflow(s): explains how work in the repository is done. This might include a series of commands or skill calls. There might be multiple workflows that apply.
• Commands/Tools: if your project has root-level commands (e.g. a Makefile) that come in handy, this is a good way to make your agent use them. This will ensure that the agent is executing certain flows consistently.
• Authority/Guardrails: what the agent can do and not do without the user’s permission (e.g. “do not commit code without my permission”).
• Rules: these might describe ways of working or certain things to avoid while doing repetitive tasks (e.g. “do not reference task IDs in code comments”).
• Docs/References: usually during agentic workflows a stack of knowledge is created that goes in a folder like docs. This is where you’d like to tell the agent about it and explain the purpose of different sub-sections (e.g. docs/planning, docs/decisions).
• Sub-agents (Advanced): when you run a multi-model workflow, specifying what kind of agents should be used can prove very valuable, especially for simpler tasks that can be handled with quicker, cheaper models with disabled reasoning.

Mitigating context rot and agentic drift

Context rot is the biggest issue when working with agents. Simply put - they forget and get confused. Over the course of multiple compactions, the agent will have little to no knowledge about what you did before that.

A few techniques to avoid it:

• Don’t stay too long in sessions where context preservation is important. Use additional tools to save the state of work to be referred to or handed off to another session. Start new sessions for your next task.
• Instructions in the system prompt that grow too big can usually be exported as skills.
• Delegate complex tasks to sub-agents which run specific skills. These sub-agents will start with a fresh session and won’t suffer confusion from your main one.

Advice for writing good system prompts

There isn’t a definitive framework for how system prompts are written, so it makes sense to create your own. You will find yourself repeating instructions across projects to persist the behaviour that you like. Having a way to propagate those without rewriting them manually is essential, so creating a toolkit for managing them can be very helpful.

I personally have a tool to create new repositories with an AGENTS.md template that I consistently improve. I also have skills for AGENTS.md authoring and verification, in which I add rules (e.g. “agents should never read the contents of docs without the call made by a skill”).

Skills and when to write one

A repetitive task in AI slang is also known as an inner loop. Identifying such tasks is what creates your skill toolkit. For most software engineers this would be things like: bootstrapping a project with a specific framework and creating common boilerplate, writing and auditing code, searching for security issues, etc.

I highly recommend writing skills and system prompts by hand first, so that you can learn the pitfalls yourself, but using an agent to write them for you becomes invaluable for structure, correctness and completeness. There are various ways to start writing efficient skills. I suggest looking first at the wide variety of open-source examples(opens in new tab) before starting your own.

Anatomy of a skill

Skills are made of a bunch of files that are either global or project specific. These are usually placed in .agents/skills/<skill-name> inside your project’s repository (.claude/skills/<skill-name> for Claude) with SKILL.md as the main (entry) file. For complete and extensive documentation on how agent-agnostic skills are written, refer to the official agentskills.io specification(opens in new tab).

The frontmatter

This is the header part of the SKILL.md which describes what the skill does and how it is used. It looks something like this. These are the required properties that every skill should have:

---
name: readme-writer
description: Write, rewrite, or trim README files so a human grasps the project in one pass.
---

This would create a skill called readme-writer. After creating it, it can be manually invoked. This is done differently across different agents: Codex uses $readme-writer, Claude and Cursor use the /readme-writer pattern, and other agents like pi and opencode use /skill:readme-writer. Check your agent’s documentation for more information.

Besides you running the skill manually, the agent might decide to do it based on its description. In this case, if it’s editing the README file, it might choose to do so. It’s a matter of “does the agent remember it or not?” (context rot might betray you here).

There are additional, optional, properties that can go in a skill’s frontmatter:

• license: as with any other open-source or proprietary software license, this can be included with a skill
• compatibility: a description, up to 500 chars, of the environment requirements that the skill needs in order to run (grep, node, linux, windows, etc.)
• metadata: additional skill information such as version, author, etc. written as key/value pairs
• allowed-tools: the list of shell commands which the skill can run (e.g. Bash(git:*) Bash(jq:*) Read)

Skill arguments

Skills can be built to include arguments (parameters). For example, generate-report period:annual or generate-report period:quarterly. While this approach works well, the agent will still understand how to run the skill when you use natural language such as /generate-report annual.

The SKILL.md body

It’s harder to define a reusable structure for skills, as they greatly vary based on their purpose. Here are, however, a few things that apply to most:

• Procedure: a step-by-step list of instructions to follow to get the job done. This should also include a verification process that produces a report with evidence that the job has completed successfully
• Rules: things to do and things to avoid; keep those separate from the procedure
• References: links to the building blocks of a skill and how to use them

References, scripts & assets

These are additional components that supplement SKILL.md and are explicitly referenced by it. They’re never automatically loaded. They follow the official agent skills specification(opens in new tab) and are expected to live in folders called references, scripts and assets, but this is not enforced.

References

These are additional markdown documents to be conditionally loaded. Imagine you have a skill called report-generator that follows the same rules, but there are 3 different domains for which the reports are built - financial, executive and marketing. These might work off the same dataset, but produce completely different output in different formats with different annotations. In this case, you keep the instructions for different kinds of reports in separate documents, loaded by the agent based on the kind of report you’re generating now.

Scripts

Scripts are the tools that your skill is going to use to “operate heavy machinery”.

When a skill runs a more complex operation that requires executing multiple commands in order, it’s best to avoid writing it down as a procedure of multiple steps, but to have this as a reusable script. This is not only going to reduce context and token usage, but is also going to guarantee that the sequence of commands is going to be executed exactly the same way every time. For example: download an image from S3, reduce image size, compress, upload back to another S3 bucket. This is best exported in a script, which takes arguments like --source-file, --convert-to, --resize-to and --target-bucket, which is called every time correctly.

Scripts are the bread and butter for skills with complex workflows.

Assets

These are usually documents that are used verbatim by the skills and usually boil down to template files and boilerplate. This might include configuration files, HTML templates, anything that is copy/pasted as-is or with little to no change.

Final thoughts

Your system prompt and skills are virtually the most important parts of your agentic workflow bootstrap. There are many things that professionals use on top of that, but these are the building blocks for a successful CI/CD with agents. The primary risks to consider:

• Be diligent about how to organise them and make them vendor agnostic.
• Create a toolkit for managing them, but not too early. Engineer for improvement, correctness and efficiency.
• Reference open-source as research, but avoid using out-of-the-box solutions, as these are heavily prone to prompt injections, even from verified sources. Accounts get hacked heavily nowadays.

How this article changed

The January 2026 version of this article documented a manually built set of basic commands and explained how I used them. All of them are gone now and replaced by superior workflows. In the latest update the entire post was rewritten from scratch and focuses better on how system prompts and skills should be written.