By now, there is plenty of literature of generative recommenders, and there are companies already productionizing generative recommenders ¹.

To understand literature on generative recommenders, you should be familiar with the design decisions of generative recommenders ². I write the key design decisions in this blog post.

Traditional recommendation systems

Traditionally, recommendation systems have two separate models for retrieval and ranking.

• The ranking model predicts a list of P(action), given features.
  • Features generally come from three sources
    • user features (account age, last interacted content)
    • item features (item popularity, item topics of the most recent interacted content)
    • interaction features (whether the user “follows” the author)
  • Features generally fall into two types
    • dense features - each dense feature is a float number
    • sparse features - each sparse feature is a list of integers
• The retrieval model “two tower model” produces a pair of embeddings
  • a user two tower embedding for a user given user features
  • an item two tower embedding given item features
• Offline processes
  • Ranking model is trained
  • Retrieval model is trained
  • Item two tower embeddings are calculated with the retrieval model, indexed in a vector database
• Online queries
  • The user two tower embedding is calculated with the retrieval model
  • Items with the most similar embeddings “candidates” are retrieved from the vector database
  • The list of P(action) is calculated for each candidate

A baseline implementation of a generative recommender

I am describing an implementation of a generative recommender, not the implementation. I think this implementation is the simplest end-to-end generative recommendation. We will discuss design decisions of a generative recommender in future sections, with reference to this “baseline implementation”.

All items are represented with a semantic ID triple.

• The number of possible semantic IDs is 1000. This means the number of possible semantic ID triples is 1 billion.
• There may be multiple items with the same semantic ID triple.
• There may be semantic ID triples that do not have items.
• The semantic ID design decision is out of scope for our discussion here. We assume we have an ideal set of semantic IDs.

All users are represented by their history of items.

• If you skipped item 1 (i1), clicked on item two (i2), the relevant part of the history would look like (i1-s1) (i1-s2) (i1-s3) (skip) (i2-s1) (i2-s2) (i2-s3) (click)
  • where i2-s3 refers to the 3rd element of the semantic ID triplet of item 2.
• Offline processes
  • The generative model is trained to predict every next token in the sequence
  • During indexing
    • You calculate the semantic IDs of each item
    • You store ordered lists of semantic ID triples to items
      • You also store ordered lists of semantic ID prefixes to items
• Online processes
  • The generative model generates multiple semantic ID triplets to retrieve
    • Content with the same semantic ID will be retrieved
  • The generative model predicts the action token for the item
    • The P(skip), P(click), P(downvote)
    • There will be a value function that decides how to weigh the action probabilities
      • For example P(skip) + 10 * P(click) - 100 * P(downvote)

Key benefits of a generative recommender

One model for inputs

• For a user with k interactions, the user is one sequence in the dataset
• The idea that training on a sequence trains on many objectives at the same time (cite Jason Wei blog)

One model for outputs

• New product surface can reuse the user history and recommender model
• DLRM cannot do this
• Easier maintainability (if done correctly)
• If you want to continuously train the model, you only train one model.

One value to rule them all

• No more constraint system

Infrastructure and tooling for LLMs

• There are tools that efficiently serve LLMs out of the box and form great benchmarks
• You can actually see how individual parts of the history affect the final prediction

Interpretability

• It is much easier to perturb sequence history than features.

Design decisions

Item representation

In the “baseline” implementation, each item is represented with a semantic ID triplet, and nothing else.

Design decisions in the item representation

• Information to include
  • Pure ID
    • Each item has its own ID
    • This is not sustainable in large scale recommendation systems
  • Semantic ID
    • There is a decision to be made
    • One implementation of Google uses eight (citation needed).
    • Eugene Yan’s implementation uses 3 (cite his blogpost).
  • Include realtime information
    • Examples - freshness, popularity
    • We could have a token that indicates the popularity of the item
    • (Number of likes and upvotes at the time of interaction)
  • Include author information
    • We could have something like an author semantic ID
    • We could include the popularity of the author
  • Include interaction information
    • Whether you follow the author at the time of impression

Putting it together

In the baseline implementation the item

(i1-s1) (i1-s2) (i1-s3)

With the augmentation I described

(i1-s1) (i1-s2) (i1-s3) (age-s1) (popularity-s1) (author-s1) (followed-s1)

Note the order of the augmented information. I place the augmented information after the semantic ID triplets. The augmented information is only available after retrieving with the semantic IDs.

User representation

• In the “baseline” implementation, each user is represented with an item-action pair sequence, and nothing else

Decisions

• Information to include
  • User context information
    • In what context was the user exposed to the item?
    • Examples: device type, entry point, time of day
  • Completeness of information
    • Not all actions by the user involve an item
    • Example includes going to the setting page to turn off notifications
• Handling excessive user context
  • We are likely to have users that have hundreds of thousands of interactions with the platform.
  • We need to decide what information to exclude

In the baseline implementation, the user is represented as a sequence like

(i1-s1) (i1-s2) (i1-s3) (skip)
(i2-s1) (i2-s2) (i2-s3) (click)

With the augmented information, the user is represented with something like

(visit homepage) (device-id-s1) (referral-id-1)
(i1-s1) (i1-s2) (i1-s3) (skip)
(i2-s1) (i2-s2) (i2-s3) (click)
(follows author-1)
(installs app)

Retrieval

In the baseline representation, the model will predict a set of semantic ID triplets. Content matching the semantic ID triplet is retrieved. If there is insufficient content, content matching a prefix of the semantic ID triplet is retrieved.

Unlike two tower, there is no embedding retrieval.

Decisions on semantic ID retrieval

• You want a set of semantic ID triplets for retrieval
• You can do something like greedy best-first search
  • You start with the greedy sequence (each token chosen in the triplet has the highest probability)
  • Then for each prefix you greedily choose the highest probability next token that is not already chosen
  • You end up with a set of semantic ID triplets with the highest probabilities
• There are likely other strategies
  • You can validate this by figuring out which strategy maximizes the value function later

Ranking

In the baseline representation, the model will predict the action probabilities

(i1-s1) (i1-s2) (i1-s3) (skip)
(i2-s1) (i2-s2) (i2-s3) (?)

In traditional recommendation systems, you do pointwise ranking. You rank everything at once. You apply some business rules such that you do not show the same creator twice.

In a generative recommendation system, you can autoregressively generate the sequence. The second content to recommend depends on the first content to recommend. If you really like a creator, the system should not prevent you from showing consecutive content from the same creator.

Pretraining

In the baseline implementation, training is done from scratch. There is no need for the model to be good at English and semantic ID.

Decisions

• Model architecture
• Initialization weights
  • Maybe just start from random weights
  • Do you really need your model to be good at math or human language?
• What is masked
  • Do you really need to mask user device for example?
• Metrics that you should look at
  • Should you just look at validation loss?
• How often should you pretrain your model?
  • Pretraining is expensive.
    • For a model of X million activated parameters, each with an average sequence length of Y, for Z users, even without counting the quadratic attention term, you need at least XYZ floating point operations.
      • Note that each entry point of DLRM training is one interaction, whereas each entry point of generative recommender model pretraining is one sequence.
      • In one backward pass for a sequence, you are training the model to predict the whole sequence, which usually contains many interactions.
  • You might want to pretrain a model every month.
  • You might want to pretrain a model as you add richer sequences
    • Maybe your first implementation of the generative recommender is the “baseline” recommender, which is shipped to everyone.
    • Then you want to add richer sequence information

Posttraining

You might be doing this every day, or even continuously.

Decisions

• Should you serve only one post-trained model?
  • Of course in A/B testing you should serve multiple post-trained models
  • Should ranking and retrieval use the same post-trained model?
  • Should different surfaces use the same post-trained model?
• What offline metrics should you look at?

Analysis

What do you want to analyze when you have your LLM

These are some analysis that you could do

• Attention weights
  • What tokens were used to predict the action token?
• What-if analysis
  • If the user had upvoted a content, would that change our prediction of whether the user likes the content
  • (assuming that the user also experiences and reacts in exactly the same way after the perturbation)
  • (You can also observe how all the logprobs would have independently changed)
  • (You can do this analysis in traditional recommender system)

Migration

If your product uses the traditional recommendation system, you do not just migrate to the generative recommender in one shot.

You will need to start with the end in mind.

What would the eventual state look like? You will need to make most of the design decisions early.

You need to justify your headcount and the compute expenditure. You need to propose milestones that you promise to hit.

Possible milestones

• Semantic IDs
  • Reasonable clustering
• For the ranking model
  • Match action AUC in a similar setting as DLRM
  • As you increase more data, you can achieve better action AUC
• For the retrieval model
  • Match recall@K

What would the end state look like? You do not want to migrate halfway and you will need to maintain both systems. Will your company still even be around when you finish your migration?

Iteration

Congratulations in advance on your migration to generative models.

This is still not the end, it is always likely there is room for improvement.

You want to design a system that can be easily iterated on.

These are components that could be iterated on

• Semantic ID
• Model architecture
• Sequence modelling (item and user representation)
• Post-training
• Value function

Let’s say your entire system is built on semantic ID. Then you find out that half the level one IDs are effectively useless because they map to spammy content. If you want to replace the semantic ID, you need to replace the entire system. You need to pretrain a model in parallel, you need to serve models in parallel. Your A/B test will involve all the surfaces. If you do not design your system to easily change and test any component, you will be stuck with those components.

Conclusion

I hope this is a comprehensive list of the design decisions when building a generative recommender.

Footnotes

I won third place. The prize was $1,000 of Modal credits, $1,000 of ChatGPT credits, and 6 months of ChatGPT Pro.

I was admitted to the hackathon two days before the hackathon - I signed up three days before.

At that time I was already working on setting up my environment for ARC-AGI-3.

This is what I already had

• Some neural network that was inspired by AlphaGo
• Ideal gameplay traces
• Submission pipeline

I made some preparations before the hackathon

• I made some “modified games”. “Modified games” have the same engine logic as the games published by the ARC Foundation, but with slight modifications. For example, for the “original game” ar25, the shapes of the objects were made different.
• I generated the ideal gameplay traces on the modified games.

Autoresearch objective

I only started the autoresearch system halfway through the hackathon. The purpose of the autoresearch system is to figure out a good neural network model that is able to predict actions.

The model will need to

• predict which of the six actions (up, down, left, right, space, click) will be taken
• predict which color (among the colors present in the frame) will be chosen
• predict which coordinate (among the coordinates of the chosen color) will be clicked

The loss function is cross entropy. Color and coordinate logits will be masked if irrelevant. The loss for color and coordinate will not be computed if irrelevant.

Each action taken by the agent is transformed into a 384 x 64 x 64 matrix for input. I defined the transformation.

The training data is the ideal gameplay actions on the modified games. The validation data is the ideal gameplay actions on the original games.

I set up a system for the agent (Claude Code) to experiment with different model architectures that minimize the validation loss.

Performance

Each training loop takes between 5 and 30 minutes. The free tier of Modal allows you to use 10 GPUs at once.

This is the “autoresearch” graph. The agent started with a model architecture with a validation loss of around 4.5, and eventually found a model architecture with a validation loss of 3.5.

For the model that achieved a validation loss of 3.5, the model initialized with a training loss of 12.0 and somewhat converged to a training loss of 2.0.

However, when playing even the games that it has trained on, I have no evidence that the trained model is performing better than a model that simply takes random actions.

Things I remembered I had to intentionally design

The only job of the autoresearch agent is to figure out the model architecture. I want the agent to assume that the data is fixed, and focus on optimizing the model architecture. I decided that I would be the one to transform the game state into the model input (384 x 64 x 64).

Every model tested should be a standalone file that should not be modified after testing. Initially I discovered that the agent modified the model architecture code after testing - this is bad because it makes it very difficult to understand exactly which model architecture produced a given result.

Validation loss should only be calculated at the end. I want the training to be done quickly so that the agent can iterate on model architecture. Maybe I could instead set up a system to export the current model and calculate the validation loss at every quarter of the data without blocking the training process.

These are some things I learnt

Data is important. I spent more time on the data than on the autoresearch system, and I still think I need to spend more time on the data. I still do not have the confidence that I am curve-fitting on a reasonable dataset. I also suspect that I might be somewhat leaking the targets in the input.

Data shuffling is hard. You want your data shuffled so that you can trust that the training loss has decreased. You cannot load all the data in memory and generate the shuffle. A simple filesystem where you have one file per datapoint would not scale. This is something I must consider when I work on something similar.

Validation score is a distribution. There was a model variant that hit 3.5 validation loss, and for a while, other model variants could not beat the score. When the agent decided to rerun the training for that model variant, the validation loss was 3.9. This means that scores on the frontier can be noisy. One remedy is to encourage experiments to be repeated and frontier scores updated.

Validation loss does not really mean anything. I used the trained model to play the games that it trained on, and its performance is bad. It could not clear even the first level. Even if I were to scale the amount of data, I do not think the model can learn to play a quarter of the games it has trained on. (Note that for the ARC-AGI leaderboard, the model will need to solve games it has not seen.)

Code quality is important. The code I wrote in a short time has a lot of hacks. For example, I need to decide whether I should treat each “modified game” the same as an “original game” in my system. I also have to ensure that my system works with multiple external abstractions - ARC SDK, Kaggle notebooks. I think I will be cleaning up most of the autoresearch code in the main repository.

Learning needs to be intentional. The autoresearch system treats each training cycle as a black box. The agent modifies the architecture, runs the training script, and reports the loss. It does not attempt to understand why one model architecture is better than another. Optimizing merely for the validation loss may be optimal if you want to produce immediate results, and this is the correct decision in a hackathon. However, neither the agent nor I am learning anything, and we are very far from solving the main task of training a model to play games that it has seen in training.

I argue that all frontier coding harnesses will soon be using only interaction models.

What is an interaction model

Current frontier models (Opus 4.7, GPT-5.5) that we interact with are non-interaction models. They have one output stream. They are next-token predictors - they write one token at a time, each token conditioned on everything that came before, and have to finish one thought before starting another. To do two things, they have to do one and then the other.

An interaction model runs many channels of input and output in parallel, instead of one stream that takes turns. It can think on one channel while it writes to you on another, while it watches a tool’s output on a third, while it edits a file on a fourth. The streams are concurrent, not sequential.

On the input side, an interaction model is not waiting for a turn either. It reads your messages as you type them, terminal output as it streams, file changes as they happen, webhook events as they arrive. None of these block the others.

The shape comes from how humans work. A person on a coding task is reading the screen, hearing a coworker, typing, thinking about what to do next, and watching a test suite stream - all at the same time. An interaction model is the same shape.

Thinking Machines’ post has video demos that make this concrete - seamless dialog management, visual interjection, simultaneous speech, and simultaneous tool calls and search. The demos are voice-and-video rather than coding, but the same multi-stream idea applies.

Think of how you interact with AI coding tools

You ask the coding agent to add an “Export to CSV” button to your analytics dashboard. For each phase of the session, I describe what it is today, and what it should be.

Listening

What it is. You ask the model something like “add Export to CSV to the dashboard”. You can send immediately, or refine your statement in full (which dashboard, what is the time limit¹) before sending. You may be dictating through a speech-to-text tool like Wispr Flow, or macOS dictation.² Whatever you type, delete, or rephrase before sending is invisible to the model. The model only sees the final message when you hit send, and starts working from there.

What it should be. You ask the model something like “add Export to CSV to the dashboard”. When you complete the first phrase, the agent starts to research your code. As you modify and elaborate more, it steers the research in real time. By the time you complete your multi-sentence request, the model has already made significant progress in the research. The agent can already ask useful follow-up questions for your request.

Researching

What it is. The agent starts with a general instruction on what to do “add Export to CSV to the dashboard”. Claude Code could decide to search the codebase in parallel with Explore subagents. Claude Code writes the instruction up front for the subagent. One subagent explores the dashboard component. Another subagent explores the data query. Another subagent explores the design components. However, the main agent writes the instruction up front, waits for the subagent to return, and reads only its summary - it does not see what exactly the subagent saw. Claude Code cannot steer subagents mid-flight. Information learnt from one subagent cannot influence the research process of another subagent. This slows the overall research process, and is likely incomplete because subagents do not talk to each other.

What it should be. The agent starts with a general instruction on what to do “add Export to CSV to the dashboard”. The agent immediately starts multiple channels that investigate the different components. One channel explores the dashboard component. You do not waste tokens explaining the situation to the subagent. Another channel, with the same prefix, explores the data query. Another channel, with the same prefix, explores the design components. Information learnt from one channel is immediately shared with another channel. With each channel informed of how the other channels are doing, the research process is faster and more complete. For example, if it is discovered that we have similar data export functions for chat history, this information helps to inform the design components to use and the data queries to make. When the research is done, you also do not waste tokens writing the summary.

Aligning

What it is. There are design decisions involved in a simple button to export a CSV. Do we give a choice to the user on what to export? Is exporting instantaneous, or is the user required to check back after an hour or so for their data? These are questions you need to ask the user. There is a tradeoff on whether you want to ask the questions early, or whether you want to do your research first before asking the questions. There is a tradeoff on whether to even ask the question, because Claude Code currently does not work in the background when questions need to be answered.

What it should be. The agent should not need to make these tradeoffs. The agent could ask questions as early as they can while working on the research in the background. The agent could retract questions if they have found the answer in the resources (for example, there are data exports that are not instantaneous for data requests of smaller sizes). All responses to the agent will immediately influence the research.

Steering

What it is. The agent is already working - it has drafted the button, wired up the export handler, and is running a first export to see the output. Halfway through, you notice that the button text is not visible in dark mode. You type a correction into the chat box. Your message is queued until the next tool boundary - it feels like the agent is stonewalling you. You can interrupt the agent to get your queries immediately answered, but this discards the agent’s current progress.

What it should be. You point out that the text is not visible in dark mode. The model reads your message immediately and acknowledges your comment. The planning channel updates to include the new constraint. The implementation channel will pick it up at the next available opportunity. You do not have to wait for a turn boundary, and you do not feel stonewalled.

Approving

What it is. The agent wants to run the export against the production database to validate it on real data, and it needs your approval to do so. The agent halts and surfaces the approval prompt. You approve or deny³. Everything else the agent was doing - drafting the button, type-checking the handler - stops too. The model is single-stream, so a pending approval blocks all the work.

What it should be. The agent surfaces the approval to run the export against production on a dedicated approval channel. Only the export channel pauses. The other channels keep running - the agent continues drafting the button code and refining the export handler while you decide. If you approve, the paused channel resumes and the export runs.

Testing

What it is. Testing follows a linear process. Your dashboard has hundreds of existing tests that programmatically test each component. You need to choose a testing setup - do you stop tests on the first failure, or do you continue to run all the tests? If the agent stops tests on the first failure, the agent will not be aware of the other tests that will fail and the agent will need multiple round trips to fix. If the agent lets all the tests run, the agent will not be able to fix the first failure as soon as it can.⁴

What it should be. The agent starts testing and there is one input channel dedicated to listening for errors. There is an output channel that surfaces testing issues. If there is indeed a failure, the channel working on the code will be informed and it will be expected to investigate and fix the failure. Tests can continue to run so that if there are more test failures, they will be surfaced to the agent. We get both early fixes to failures, and reduced round trips between fixing and testing.

Compacting

What it is. The inference infrastructure is not wired to generate tokens after a certain context length. Models are also not trained to generate tokens after a certain context length. Agents need to compact their context before more tokens can be generated. ⁵ The agent cannot do anything when it is compacting.

What it should be. Compacting should be done in parallel. As the agent works on the problem, there should be another channel that decides which information is worth storing and which information should be removed from context. Information removed from context should still be searchable from any channel.

Improving

What it is. After you ship your feature, you want to improve your future experience working with the model. You write and improve skills that help you do your work more efficiently. For example, when testing the dashboard, the agent should remember to try both light and dark mode and confirm visibility of every text element. The agent will need to search their history and correctly surface pain points that could have been informed with skills.

What it should be. Reflection happens continuously in a dedicated channel that the agent maintains throughout the session. When the agent finds out that the button text is not visible in dark mode, the reflection channel should note down the issue in parallel. When the feature is shipped, the agent will propose to make improvements to AI instructions.

Implications

If interaction models are coming, here is what I think changes for users, builders, and the model market.

Humans will prefer the better interface

I still prefer Claude Code as my main interface.

For most of the work that I do, it is not possible for me to give perfect instructions in the first turn. I also operate with imperfect information, and I do not have all the answers. I need to interact with the agent to understand the problem together.

For me, Claude Code still feels easier to interact with.

I do not really care whether one model is slightly more intelligent than the other. I care about how easy it is for me to communicate with the agent and get things done.

The companies that ship interaction models first will set the floor for what users expect. Going back to a single-stream model will feel like going from a chat app to email.

Current interfaces will continue to be supported

Coding agents using interaction models should not require you to turn on your webcam and microphone.

You should still be able to talk to your coding agent with chat, just that it is more responsive and effective.

For users, you should continue to be great at using the current text-interface AI coding tools.

You will still need to teach your coding agent

The coding agent does not know about your business.

You will still need to teach your coding agent the environment you are working with. Even with interaction models, the model still starts every session afresh.

You will still need to manage instructions and resources for the agent to access. Skills will continue to be written. Resources will still need to be accessed.

The model will decide everything

Currently the harnesses manage plenty of decisions - for example, whether to compact, whether to auto-approve a command, and the context reset after planning mode.

A lot of the harnesses are built with the assumption of a single-stream model - compaction, monitoring, chain-of-thought. Prompts are written and evaluated. With this, I think most of the harnesses that we use today will be thrown away.

If I am building yet another coding tool, I will make the harness work only with interaction models.

There will be one coding model size

My bet is that the coding model market will collapse to one model size served via API⁶.

Currently Claude Code by default is served with two models - Opus as the main model and Haiku as the explore model.

With interaction models, everything will be one model, which means one model size.

There will be different knobs that the model can decide to turn for itself.⁷

Closing

Coding is the first killer use case for LLMs.

I think coding will also be the first killer use case for interaction models.

All coding models will be interaction models⁸.

Footnotes

The main material available is the pyramid visualization from the Flash Attention paper.

I wanted the visualization to be animated. I did not manage to find a good resource out there ¹. So I made mine.

The animation was made with MacOS Keynote, manually. ². As of writing, it appears to rank second on Google search.

I also wrote a Quora answer explaining how Flash Attention works.

I asked in the GPU Mode Discord for opinions on my work.

gau.nernst replied with the following comments, which I greatly appreciate.

i wanted to comment that the loop order was reversed. but upon checking, turns out FA1 used this loop ordering, but FA2 reversed it (and I only read the FA2 paper lmao)

so in FA2, iterating along K/V is the inner loop, iterating along Q/O is the outer loop, which is implemented as 1 threadblock handling 1 Q/O tile

yea I think FA3 and FA4 also follow the FA2’s general design, but optimized for Hopper and Blackwell respectively

The explanation may not be complete, the details may not be fully correct, but I still hope this makes it slightly easier for you to understand Flash Attention.

Footnotes

The writeup with the links is available on Kaggle.

This is the first time I won prize money from Kaggle competitions.

Think of the most capable person that you have ever worked with.

You hire them into a new company.

There are still things this person could have done more “accurately” and “efficiently”.

Think of what they will need to learn between the first day they join the company until the day where they become effective individual contributors. They will need to learn where to look for information. They will need to know who to approach to access privileged information. They will need to learn the processes necessary to ship things. They will need to learn the pitfalls that they should avoid.

Humans have memory and they could remember things. For AI coding tools however, every time you start a chat, their memory is reset. They know absolutely nothing about your company at the beginning of each session. ¹ You need to teach them again.

This teaching process could have been accelerated with skill files.

I want to encourage my colleagues to write and maintain skills to accelerate their work. Here I describe how I am doing it.

What exactly are skills?

Skills consist of three elements at minimum:

• Skill name
• Skill description
• Skill content

Let’s use writing a commit message as an example of a skill.

---
name: write-commit-message
description: Commit message guidelines. Use when writing git commit messages.
---

<skill content>

When the AI coding tool starts a session, it will load the skill name and skill description into the model context.

This is what you see in Claude Code when you run /context.

Skills · /skills

Project
└ write-commit-message: 21 tokens

When the agent needs to write a commit message, it should decide to invoke a skill. When the skill is invoked, the agent will read the skill content. In this case, the skill content contains the information on how to write commit messages.

Why do we need skills?

Skills are needed to instruct the agent on how to do things more accurately and efficiently.

On writing commit messages, the company likely has some standards on how commit messages should be written.

For example, the commit message should contain this information:

• How to write the commit title
• What to include in the commit description (context, design decisions, test plan)
• What not to include in the commit description
• Who the reviewers are
• What URLs need to be included (for example Slack, Asana)

If agents want to write commit messages accurately without additional instructions, they will need to figure out these requirements by looking at similar commits, or running the unit tests related to the commit message.

However, if you require the agent to learn the commit message pattern on every session by reading many similar commits, this is not efficient. If the agent skips the learning process, the agent is not being accurate. This will still be the case even as models get better, because not every company has the same commit message standards.

Writing commit messages could have been done more accurately and efficiently². Skill files allow this. When the agent is going to write commit messages, it will “invoke the skill” and read the skill content.

Initially I placed the commit message standards in CLAUDE.md / AGENTS.md. This was a reasonable place to put the instruction because it is globally relevant. I have been advocating for CLAUDE.md to only include globally relevant information. However, this means the commit message instructions are loaded even when the user is not writing a commit message, for example when asking questions about the codebase. There is room for improvement here, regarding efficiency.

Then I moved the commit message standards to the git commit template. Instead of placing the full instructions in CLAUDE.md, I added a pointer to the git commit template. This is what I have been doing before we had skills. This still follows the progressive disclosure principle, because I load the commit message standards only when I write the commit message.

Even though placing the commit message standards in the git commit template fulfills the principle of progressive disclosure, there is still benefit in making write-commit-message a skill. We want to centralize our AI instructions instead of scattering them over the codebase. When we implement telemetry and feedback loops for skills, write-commit-message can also benefit if it is a skill.

When you should write a skill

If you want a process to be done more accurately and efficiently with AI coding tools, you should write a skill. These are some examples where you should think about writing a skill.

You have a resource that you want your agent to access. The resource could be Notion, Slack, Asana, or any internal pages. Instead of playing telephone between the AI coding tool and the resource, you can write a skill that teaches the agent how to read the resource. However, this assumes that your AI coding tool has access to the resources, which you will have to set up first.

You execute repetitive processes that you want automated. For example, every day I am supposed to check the feed statistics for our recommendation system. This involves looking at dashboards. If there are significant movements in the metrics, I need to explain it by looking at commit logs. This should have been a skill.

You want a process to be done more efficiently in the future. One such process is on-call pages. You might already be handling on-call pages with AI coding tools that have access to dashboards and error logs. In the future, you want to handle this more efficiently. You can write a skill that informs the agent of the resources that it should look at and the dead ends that it should be aware of.

There are cases where you should not write a skill.

• Tasks that the agent could already solve accurately and efficiently. For example, you should not add a skill on how to search the code, because the agent is likely already searching the code in the most efficient manner.³
• Features that the AI coding tool should already be good at. There should not be a plan-mode or clarify-user-questions skill because AI coding tools should already include this in their system prompt.
• Workflows that should have been a deterministic script. If you are writing a check-commit-message skill, you should not be asking the agent to run checks that could be unit tests. The agent should not be an expensive linter. If there is still value in writing check-commit-message to check the qualitative aspects of the commit message, the skill should ask the agent to run the relevant unit tests for the deterministic checks.

Skill writing advice

Start by writing the simplest possible skill that is worth using.

You could look at what you did in the past week and think of:

• The documents that you need to repeatedly write or review
• Questions that you need to repeatedly answer
• Investigations that you need to repeat

Then, think whether any of these processes could be done more accurately and efficiently with AI coding tools.

If so, you have found a good candidate for a skill.

Then write your skill. Start simple, with only a SKILL.md file.

---
name: <name>
description: <description>
---

<What exactly the skill does>

Example queries
- <example query>

# Workflow

<step by step process>

Checklist
- [ ] Item 1
- [ ] Item 2

# Pitfalls to avoid

<list them>

After writing your skill, you should test it. When you commit your skill, you should include evidence that it is tested. Unlike unit tests, testing a skill is not deterministic, but you should still provide evidence of testing.

Here are some good forms of evidence:

• If the skill output is a document, the resulting document could be evidence.
• If the skill provides instructions on how to read a resource, you could start a new session to see whether the agent could invoke the skill and read the resource without tripping over issues.
• If the skill helps with an investigation, the investigation thread could be evidence.

Your colleagues will review your skill, just as code is reviewed in the codebase.

Managing skills for the company

As hundreds of colleagues commit skills into the codebase, you will soon have hundreds of skills.

This means that you will have hundreds of skill names, and hundreds of skill descriptions. If each skill is 50 tokens, this will be 5000 tokens. Also depending on the quality of your skill descriptions, the agent might invoke skills unnecessarily, or fail to invoke skills when it is needed.

If you look at the skills, there are skills that are company-wide and there are skills that are team-wide. You should only load company-wide skills into context.

This can be done in Claude Code. For team-wide skills, add disable-model-invocation: true to prevent the skill from being loaded in context.

---
name: investigate-speed-feed
description: 
disable-model-invocation: true
---

<skill content>

This will mean that if you go to Claude Code and ask “please investigate feed speed”, the skill will not be invoked. You need to write /investigate-speed-feed. This is fine, because people who need to use the skill should know about the skill.

By separating team-wide skills and company-wide skills, and requiring all team-wide skills to have model invocation disabled, you reduce the risk of the agent not invoking necessary skills or invoking unnecessary skills⁴.

Organize the team-wide skills and company-wide skills into two folders.

skills/
     ├── company_wide/
     │   └── write-commit-message/
     │       └── SKILL.md
     └── team_wide/
         └── investigate-speed-feed/
             └── SKILL.md

However, the skill standard requires all skills to be at the same level.

Then symlink every skill folder into skills/all.

skills/
     ├── all/
     ├── company_wide/
     └── team_wide/

.claude/skills, .cursor/skills, and .codex/skills are soft symlinks to skills/all.

To enforce that skills follow the intended format, you should write unit tests to test skills.

For example, you could have unit tests that check that

• The skill name is short
• The skill description follows convention ⁵
• Whether the SKILL.md file is under 500 lines
• Required components in the SKILL.md file (I require example queries to appear as its own section within the first 50 lines.)
• Whether the symlinks are added correctly

As the skills maintainer, you need to define your responsibilities. You should not be reviewing every line of every skill. If there is an issue with a skill, you should direct the complaint to the owner of the skill. You can give advice, but should not be required to.

There are still responsibilities that belong to you as the skills maintainer. For example, if a skill is not invoked when it is supposed to, or unnecessarily invoked, you need to investigate. It might be the issue of how the user queries the model, how the skill name and description is written, or it might be the fault of the model or the AI coding tool. It is still your duty to triage and provide advice here. Periodically, you also need to review how skills are written and identify anti-patterns and legislate against these anti-patterns.

To help your colleagues write skills, you write a skill that helps them write skills.

Initially I used Anthropic’s skill-creator skill to write skills. However I found out there are many unnecessary parts. For example, there is no need for the init_skill.py steps that create all the resource directories. Skills should start simple with just a SKILL.md file.

To help your colleagues improve skills, you again write a skill that helps them improve skills.

There will be a skill-feedback skill where agents can provide feedback on skills. Feedback should be provided when the agent finds an inaccuracy in the skill file, or pitfalls that the skill has not documented. The feedback will be stored in some data lake, which should be queried when we iterate on skills.

I hope this helps you write and improve skills for your company, so that the agents can do things more accurately and efficiently.

Footnotes

These are some evaluation test cases that I think LLMs should no longer be evaluated on.

Tasks on recalling facts not critical to your work

There are evals that test whether the LLM remembers certain things (MMLU).

This is the README example in MMLU dataset.

{
  "question": "What is the embryological origin of the hyoid bone?",
  "choices": [
    "The first pharyngeal arch",
    "The first and second pharyngeal arches",
    "The second pharyngeal arch",
    "The second and third pharyngeal arches"
  ],
  "answer": "D"
}

I argue that this is an unreasonable memorization task¹. LLMs do not need to memorize this to be helpful. Neither do doctors need to memorize this to execute their work.

Even as we do not expect LLMs to always provide the perfect answer to this, we still expect AI systems to solve this task perfectly. AI systems are more than just models. AI systems involve LLMs having access to tools such as web search.

Tasks on recalling from a super-long context

There are currently evals that test whether a model can retrieve a specific piece of information buried in a very long context. Model providers boast that their models could memorize the context well into the millions.

I argue that this is a non-goal. Humans can solve very long problems without the ability to memorize the entire conversation history. A math professor does not need to recall what they did exactly 300 days ago to solve an open math problem that requires a lot of research and trial and error.

The goal here is to solve complex tasks with the minimum compute. I expect the solution to involve an AI system where the LLM manages its own context and queries previous context with tools. The solution does not necessarily require a model that is able to retrieve something within a million tokens.

This means I still expect AI systems to be perfect at super-long context retrieval. LLMs should be able to use tools to query the history and perfectly retrieve any specific piece of information.

Tasks that require a playbook

Some evaluations test whether an LLM can answer domain-specific questions - legal advice, medical diagnoses, tax regulations.

You cannot expect a lawyer to do well at their job without access to the legal resources. Similarly, you cannot expect the LLM to perform as well as the lawyer without access to the same set of legal resources.

LLMs should have baseline domain knowledge, like a human professional would. We should avoid having evals that simply test the LLMs without providing them access to the necessary legal resources.

Tasks that are better served with tools

Some evaluations test raw computation - multiplying large numbers, performing complex arithmetic, counting characters.

We should not be evaluating LLMs on whether they can do 100-digit multiplication without chain of thought. LLMs should be able to figure out and follow recipes to do 100 by 100 digit multiplication in O(n²) tokens.

LLMs should be evaluated on whether they can discover and execute algorithms, not whether they can compute magically².

Tasks based on noisy data

We should not use the same mindset we used to participate in traditional Kaggle competitions to train LLMs.

In traditional Kaggle competitions, you do whatever it takes to maximize your score on the leaderboard, even if it means training on incorrect labels in the training set. We should not carry this mindset to evaluating LLMs.

I expect model providers to remove inconsistent or ambiguous test cases when evaluating their models internally.

Summary

I hope we apply higher scrutiny to the test cases we use to evaluate LLMs.

I also hope that you understand the difference in standards that we apply to LLMs and to AI systems. There are tasks we expect AI systems to solve perfectly, but do not expect LLMs to get correct.

So when an LLM fails a benchmark task, ask yourself: is the model wrong, or is the task wrong?

Footnotes

hamel.dev/blog/posts/evals-faq/

Many of the ideas I have been promoting¹ align with the Evals FAQ.

The content here does not represent the prevailing opinions or practices of any organization.

Sections that I agree with and promote

These are ideas that I have been promoting. I should have cited the Evals FAQ when promoting my ideas.

On binary (pass/fail) evaluations instead of 1-5 ratings (Likert scales).

Having binary options forces people to make a decision rather than hiding uncertainty in middle values. Binary decisions are also faster to make during error analysis - you don’t waste time debating whether something is a 3 or 4.

For example, you want to classify whether content is adult. You might want to ask for a scale of 1 to 4 instead of a binary classification. On the adult side, you want a label of 1 if the content is CSAM that you have to eliminate from your platform, and a label of 2 if it is merely adult. On the less adult side, you want a label of 3 if it is provocative that you do not want to show to new users, and 4 if the content is perfectly fine. Only users who opted in to adult content will see content with label 2.

I would rather we have three binary classifiers - on whether something is adult (1+2 vs 3+4), on whether something is CSAM (1 vs the rest), and on whether something should be shown to new users (4 vs the rest).

There are some arguments for having one classifier for all 4 labels

• You intend to run the LLM for all your content. You think running the LLM only once saves you money, compared to running the LLM three times for three separate classifiers.
• You think that having one system is simpler, as opposed to multiple systems. You think that one system is easier to maintain.

I argue that you should think harder about whether having a graduated 1-4 scale is really a better system than having three binary classifiers.

• You need to think about what happens when you want to change one of the systems. Let’s say you want to have a different standard on what is allowed to be displayed to new users (label 3 versus label 4). You need to ensure that your single LLM classifier still works for label 2 and label 1. Experimentation is also more complicated now.
• There might be different levels of scrutiny for different classifications - you are okay if label 3 versus label 4 is mixed up, but you do not want to mix up label 1 versus label 2 because accounts posting label 1 content will get banned.
• Aligning a binary classifier is much easier than aligning a graduated classifier. It should be easier and faster to align three binary classifiers independently than to align one 4-class classifier. It is also easier to find a cheaper and equally performant classifier if the task is just binary classification.

If your systems are uncoupled, you just need to align the parts that you need to align. Sure, it might cost more to run the LLMs three times, but engineering time usually costs even more money.

On versioning and managing prompts

There is an unavoidable tension between keeping prompts close to the code vs. an environment that non-technical stakeholders can access.

My preferred approach is storing prompts in Git. This treats them as software artifacts that are versioned, reviewed, and deployed atomically with the application code.

Prompt management tools are inherently limiting because they can’t easily execute your application’s code. Even when they can, there’s often significant indirection involved, making it difficult to test prompts with your system’s capabilities.

There is indeed a requirement for non-technical stakeholders to read and write prompts. Prompts should already be easily readable if your organization has good AI tooling to point you to the exact prompt.

There is also the case where non-technical stakeholders want to write and test the prompts² without opening a terminal or Jupyter notebook. It should be possible to keep the prompts in git while they experiment with the different prompts.

On how many people should be annotating LLM outputs

A single expert eliminates annotation conflicts and prevents the paralysis that comes from “too many cooks in the kitchen”. The benevolent dictator can incorporate input and feedback from others, but they drive the process.

I have written exactly on this before.

I argue that democracy is a horrible way to build a dataset for LLM evaluation. Let’s say you want to build dataset to determine whether an advertisement is low quality. You get your team to label the content and treat the labels as immutable ground truth. But you notice the labels provided by your team often disagrees with each other.

If you pass this dataset to your colleague, your colleague is simply guessing what people are voting. Your colleague will likely not perform well. This is what you will be tuning your prompt to.

The FAQ suggests a benevolent dictator to own the prompts, which I agree with.

Sections that I would add or edit

Evals should only focus on cases you care about. In other words, you do not need a ground truth label for everything.

For example, in adult content classification, you only want to label what is obviously adult and what is obviously not adult. If something is neither obviously adult nor obviously not adult, there is no need for a ground truth label. This means, in production, you are okay with the content being classified either way.

I think some updates have to be made considering models are much more powerful now.

• I do not think we should spend effort ensuring that every step the model takes is correct. For example, I do not think we need to care whether every search term made by the model is ideal. We know that frontier models serve as reliable agents that complete tasks. They know when they are making mistakes. As model users, we should not need to scrutinize every step the model is making; we should be more concerned with the outcome.
• I think models could play a bigger role in prompting. One new use case for LLMs in building the evaluation dataset is to brainstorm the edge cases that we care about. LLMs could even agentically query your data for mistakes the binary classifier is making in production, and put these labels up for human approval.

Sections that I disagree with

On passing 100% of your evals

Be wary of optimizing for high eval pass rates. If you’re passing 100% of your evals, you’re likely not challenging your system enough. A 70% pass rate might indicate a more meaningful evaluation that’s actually stress-testing your application. Focus on evals that help you catch real issues, not ones that make your metrics look good.

I do not agree that passing 100% of your evals is wrong in itself. Of course, you still need to justify the value of evals that you already score 100% (or any passing rate as well).

When there is a classification failure, either one or multiple parts must be wrong - the classifier (model + prompt), or the label (or the LLM-as-a-judge evaluator). You should find out which one it is. It is possible that the label is wrong³. If the prompt is wrong, you can probably tweak the prompt. If the model is wrong, you likely cannot do anything. My point here is, when there is a mistake, something must be wrong.

Mistakes are mistakes. It is possible to fix all these mistakes to get your eval to 100%. Models are better these days, and now you have AI to help you write and improve prompts. It is possible that you are not able to find any more mistakes with reasonable effort.

There could still be value for evals that pass 100%. For example, you have a classifier that classifies whether something is adult. The requirements are quite loose. You only need to classify correctly if something is obviously adult or obviously not adult. There are a lot of borderline cases where you are okay with the system tagging either way. Models today can perform 100% at this task. There is still value in this eval even though it passes 100%.

You can deploy this classifier and monitor mistakes in production. The classifier is likely to make mistakes (something obviously adult being classified as not adult), and you add the mistakes to the evaluation. Then you can tune the classifier to achieve performance on the mistakes and the initial dataset. The eval that passes 100% is still useful.

You can use the same eval when you migrate models. Models get deprecated, or you found a much cheaper model that is equally performant. The eval that scores 100% still serves as a unit test that is only run once every model migration.

What you should not do is try to add borderline examples to the dataset to make the eval perform at 70%. Similar to how “the goal of evaluations isn’t to pat yourself on the back for a perfect score”, it should also be the case that “the goal of evaluations isn’t to pat yourself on the back for an imperfect score”.

Footnotes

There will continue to be more people working on AI models and products. There will continue to be more compute. Access to compute will be better. You will also have competent AI that helps you improve AI.

AI will be human-level at manipulating browsers

The only AI-powered browsing experience that I have tried is the Claude extension on Chrome.

There are a few read-only tasks I want it to do:

• Go to the date grid on Google Flights so I can see when the cheapest flights are
• Tabulate my rent options based on listings on Craigslist
• Estimate the value of my (mostly IKEA) furniture from an image of my room

The experience is very slow and very inaccurate².

I see a few problems here:

• Every action has to be preceded by a thought process
• Context is filled up quickly and compaction is slow, because the model is trying to keep every screenshot
• The model is bad at managing multiple tabs and parallelizing work
• The model is kind of blind and only looks once³

I hope to be able to trust AI with all my read-only browser tasks. After AI earns my trust with their performance on read-only tasks, I can slowly trust AI with tasks that make changes.

Context constraints will be invisible

For the user experience, I think context constraints should already be invisible to users of frontier AI products. You should not be hit with an instruction on ChatGPT that your conversation is too long. There are some processes in the background that compact the context.⁴

For the developer experience though, you need to be aware of the context limits. In 2025, the phrase context engineering was coined.

However, I think developers will no longer need to care about context length. The model API will be shipped with context management,⁵ similar to how you talk to your friend - you do not need to ask your friend to delete old messages so that you can continue talking to them.

This developer experience should already be achievable with existing models and a suite of scaffolds. There might also be improvements in the model architecture to help.⁴

We will stop taking turns with AI

We are familiar with the chat interface with AI. You type something, hit enter, and AI replies with something. You are taking turns with AI.

The experience talking to another human is different. You take note of their facial expression and body language. You look up certain information while they are talking. You write notes to yourself. There are no explicit turns to take.

There are some efforts to break this turn-based experience with AI:

• You can interrupt while AI is replying.
• You may submit messages while AI is replying. However, how early your replies steer the response differs between products.

There are still some bottlenecks:

• Ideally the response to my question should be ready by the time I hit send.⁶
• The AI may need to ask follow-up questions to clarify my search request. But the AI should already start searching in parallel.

It is possible to achieve all this with a suite of scaffolds. There might also be improvements in the model architecture to help.⁷

AI will write their own instructions

Currently we expect models, with their harness, to complete any task with the resources available to them. They are expected to use existing instructions.⁸ Models are already expected to check their own work before reporting success.

Soon we should expect AI to not just follow processes, but also to improve the processes.

Currently, the human needs to take the initiative to prompt the model to fix the instructions. The instructions may include comments and docstrings in the code that inform future models. The instructions may be skills files that provide guides on how to execute certain processes.

We will see AI products taking the initiative to suggest changes to the process. We will see models that tastefully fix outdated and inaccurate comments in the codebase. We will see skills written, and maintained as they are being used.

Footnotes

Crafting LLM weights to multiply integers without thinking.

It is already expected that frontier models have perfect performance at multiplication without tool use. Frontier models should be able multiply step-by-step, only limited by time and space complexity.

However, I am interested in multiplication without a thought process, the model is expected to reply with the product directly.

I want to try crafting weights to perform multiplication perfectly. I will also need to study the multiplication algorithm itself.

There is this related work on training a model to perform modular addition perfectly.

Understanding segment trees.

Segment trees are an important concept if you want to get a higher rating in competitive programming. I have a template that I do not know how to use. I think I also need to understand the algorithm and the intuition behind segment trees.

Understanding Aho–Corasick algorithm.

LeetCode contests tested this two times.

• Construct String with Minimum Cost in Weekly Contest 405
• Minimum Number of Valid Strings to Form Target II in Weekly Contest 415

I solved both problems with other methods.

Tree matching problem with wildcards

You have two rooted trees. Some nodes are wildcards.

The task is to determine whether you can assign each wildcard a subtree so that you can match the two trees.

Please do not ask me where I got this problem.

Memorize the entire architecture of gpt-oss.

gpt-oss-120b is the go-to model for AIMO 3. I want to understand the model architecture very well. I need to be able to derive the parameter count, and also its GPU memory usage. I will also need to compare and explain the differences between 20b and 120b versions.

Watch some films

These are the films I have yet to watch

• Zootopia 2
• Demon Slayer: Kimetsu no Yaiba Infinity Castle
• Chainsaw Man - The Movie: Reze Arc (only watched the first half)
• Ne Zha 2
• KPop Demon Hunters
• Neon Genesis Evangelion