Skip to content

Blog

  • 2 min read

Stop wasting tokens with "When to Use" sections in your OpenCode skills

Here's a gotcha I keep seeing my colleagues run into, and that I myself tripped over when I first started writing my first SKILL.md files for OpenCode:

Sections detailing "when to use/load/activate/etc" in a SKILL.md are a waste of tokens and potential sources of context pollution!

(It doesn't help that the official OpenCode docs replicate this anti-pattern...)

Explanation

When an agent is initially loaded, OpenCode passes it a chunk of text including the system prompt, available tools, skills, other agents, as well as any custom prompt configured for the specific agent being loaded. For skill in particular, this "initial context" contains an XML table with the following structure

<available_skills>
  <skill>
    <name>skill-name</name>
    <description>
      `description` key from the skill front-matter
    </description>
    <location>path/to/skill.md</location>
  </skill>
  ...
</available_skills>

as well as additional guidance:

Skills provide specialized instructions and workflows for specific tasks. Use the skill tool to load a skill when a task matches its description.

Nowhere in the initial context are the bodies (i.e. the contents of SKILL.md) of skills. The only information about skills made initially available to agents are names, descriptions, and locations, and agents are supposed to determine whether or not to load a skill exclusively based on this information.

From this, we conclude that:

  1. description keys should ideally be terse and, above all, actionable, in order for agents to reliably load skills when appropriate. In practical terms, skill descriptions should probably include explicit guidance on when to load/use the skill. I tend to begin all my skill descriptions with an imperative "Load this skill when...".
  2. Sections in the skill body describing "when to load" or "when to use" it are basically a waste of tokens (and potentially a source of context bloat and pollution), as they are only ever read after the agent has already decided to load and use the skill.

Conclusion

So please, just stop adding unnecessary "when to use" sections in your skills. Best case, you're wasting tokens. Worst case, you're actively hampering the performance and reliability of your agents and skills by introducing sources of context pollution and noise. Just focus on writing terse, compact, and actionable description front-matter keys, and keep the skill bodies direct and lean.

  • 2 min read

Announcing ecdysis: Graceful Restarts in Rust

Updating network services without dropping active connections is a challenge. How do you deploy new code or configuration changes while maintaining zero downtime? This is where graceful restarts come in, and I'm excited to announce that we are Open Sourcing ecdysis, a Rust library for graceful process restarts originally written for data-plane services at Cloudflare.

ecdysis | ˈekdəsəs |

noun

the process of shedding the old skin (in reptiles) or casting off the outer cuticle (in insects and other arthropods).

A cicada larva undergoing ecdysis to become an adult insect

The library enables zero-downtime upgrades through process handoff and socket inheritance. It provides four key guarantees: (1) no old code remains running after a successful upgrade; (2) the new process has a grace period for initialization; (3) crashing during initialization is safe; and (4) only a single upgrade runs in parallel at any time.

ecdysis is already battle-tested in production at Cloudflare, where it saves thousands (if not hundreds of thousands!!) of requests from being dropped whenever important edge services are upgraded. The library specializes in socket inheritance and rebinding, making it ideal for network services that need to maintain active connections across restarts. It supports both synchronous and asynchronous (tokio.rs) workflows, and integrates cleanly with systemd through support for systemd-notify and named sockets.

This is a collaborative project from Cloudflare's Argo Smart Routing and Orpheus team (where Yours Truly is an IC). If your Rust service needs graceful restarts, I invite you to try out ecdysis:

GitHub Crates.io Documentation

Issues and PRs are welcome. I look forward to your feedback and contributions!

  • 2 min read

New Publication!

On Friday, my latest — and most likely, last — research article on Wearable Cognitive Assistance (WCA, one of the main topics of my Ph.D. dissertation), was finally made available on IEEE Access. Titled Emulating Reactive Workloads for Cyber-Human Systems: A Data-Driven Methodology, it discusses a methodological approach to modeling human behavior in immersive applications such as WCA. You can access (pun intended) it here.

This paper was a long time in the making. I defended my doctoral dissertation in June 2023, and I had already been working on it for about 6 months at that point. And-in-all, I estimate the total time it took us to get it published to be in the order of about 3.5 years. That's a lot, specially considering my Ph.D. program took 6 years!

To be fair though, this article went through multiple rewrites, and was submitted to (and rejected from) multiple venues before being accepted at IEEE Access. Additionally, I've been working full time as a software developer at Cloudflare since November 2022, and between January and June 2023 I spent basically all my free time writing my doctoral dissertation, so on average across those 3.5 years I probably worked an hour or two per week on this paper, at most.

In any case, it feels good to get it out there, and I stoked to finally be able to close this chapter in my life. As my former Ph.D. advisor put it, I now have finally officially graduated...

Sidenote: Double Surnames Are Difficult, Apparently

During the final publication process, I have encountered issues with the publisher not printing my name correctly. As per Spanish and Latin American convention, my complete surname is a compound of my parents surnames: "Olguín Muñoz". However, it seems like IEEE Access's editorial system has trouble with compound surnames, and my surname has therefore been entered as only "Muñoz", with "Olguín" instead being entered as a middle name. This has the unfortunate consequences that the article headers now incorrectly abbreviate my name as "M. O. Muñoz", and that the reference information generated by IEEE shows it as "Muñoz, Manuel Olguín et al."

This issue seems to have made it out to the published version of the paper, even though I raised it during proofing. I'm trying to get this fixed somehow, but to be honest I don't have very high hopes of success. It's also not the first time I've had to deal with issues due to systems (and non-spanish-speaking people) struggling with the concept of having two surnames, and it certainly won't be the last either. It seems not everyone has read the now-infamous Falsehoods Programmers Believe About Names blog post by Patrick McKenzie.

  • 3 min read

Conditional Compilation in LaTeX Using \IfFileExists And Some Elbow Grease

I recently found myself frustrated by LaTeX's lack of (straightforward at least) support for conditional compilation. I was going through the process of resubmitting a revised version of a manuscript to a journal, and needed to compile two versions of the document: a marked up version with certain parts of the text highlighted, and a "clean" one. These needed to otherwise be identical.

I wanted to be able to easily build two versions of the paper without having to change the LaTeX source to eliminate the risk of introducing accidental changes in the text. As a software engineer, my initial instinct was to attempt to find some way to pass environment variables to pdflatex, which I could then evaluate in the LaTeX source itself and trigger some behavior on their values. Unfortunately, there doesn't seem to be any simple way to do so.

However, while searching for other solutions, I stumbled upon this StackExchange question and associated answers discussing the \IfFileExists macro. The \IfFileExists macro triggers conditional behavior at document compilation time based on the presence (or absence) of a file. It is commonly used to only include certain parts of a document if the source files are present. However, I realized it's behavior is generic enough that, in combination with a build tool such as make it can also easily be used for the type of conditional compilation I needed.

To achieve this, I added the following to my document preable:

paper.tex
% conditional compilation of "review" version
\IfFileExists{./.hlChanges.tmp}{%
    \newcommand{\hllinenums}{\linenumbers}%
    \newenvironment{highlight}{\color{red}}{\normalcolor}%
}{%
    \newcommand{\hllinenums}{}%
    \newenvironment{highlight}{}{}%
}

\begin{document}
\hllinenums

This snippet checks for the existence of a temporary and hidden file ./.hlChanges.tmp at compilation time. If this file is found next to the root .tex file of the document, a \hllinenums macro and a highlight environment are defined to enable line numbers and red text highlighting in the document. On the other hand, if the file is absent, this command and environment become no-ops, and the call to \hllinenums after \begin{document} does nothing. With this, I can then wrap any piece of text I want to be highlighted in the "special" version of the document with the highlight environment. To then compile the highlighted version, I just need to create the dummy ./.hlChanges.tmp before invoking pdflatex.

I automated this process using make:

Makefile
paper.pdf: paper.tex
    latexmk -g -pdflatex -synctex=1 -interaction=nonstopmode -file-line-error -pdf $<

paper_hl.pdf: paper.tex
    touch ./.hlChanges.tmp
    (latexmk -jobname=paper_hl -g -pdflatex -synctex=1 -interaction=nonstopmode -file-line-error -pdf $< \
        && rm -f ./.hlChanges.tmp) || (rm -f ./.hlChanges.tmp && exit 1)

The paper.pdf target compiles the document without highlighting. The paper_hl.pdf target compiles the same document with highlighting by first creating the dummy file, compiling the document with basically the same options as paper.pdf, and then deleting the dummy file. Note that the ... && rm ... || rm ... && exit 1 trick is to make sure the file is deleted whether the manuscript compiles successfully or not.

I still wish LaTeX was more modern (or that typst was more widely adopted), but this did the trick for me and made the (always challenging) process of resubmitting a revised version of a manuscript slightly smoother!