Agent Skills: Code Beats Markdown (Here's Why)

Agent Skills—an open standard for “agent skills” used by models and coding harnesses—are gaining momentum because they let systems do tasks with code execution instead of relying on bulky, error-prone markdown instructions. The practical shift is toward structured skills that load lightweight metadata first, then pull in the full skill definition only when a model decides it needs a specific capability. That conditional, token-efficient workflow is why multiple companies have adopted the approach and why ecosystems like skills.sh and skillsmpp.com are emerging to publish and distribute reusable skills.

At the core of a skill is a skill.md file that acts as metadata and instruction set. Around that, skills can include references, templates, examples, and assets, but the decisive upgrade comes from scripts: code files that run inside a sandbox. With sandbox access, a model can either reuse scripts as-is or rewrite them, execute them, and then feed results back into the model as new context—or return final outputs directly to users. This turns skills into structured instruction sets backed by real tooling: bash and command-line interfaces, Python execution, and API calls.

Where things often go wrong is efficiency. Many scraping skills rely on overly generic scripts that either fail unpredictably or waste tokens. One costly mistake is using a web fetch tool to pull entire HTML pages and then returning that raw content to the model. Even a single page can balloon into tens of thousands of characters and thousands of tokens. A simple optimization—skipping script/style/nav/footer tags and similar boilerplate—can cut token usage by nearly 90%, which matters dramatically when scraping dozens or hundreds of pages.

Another common failure mode is forcing the model to rediscover page structure every run. If the target site’s CSS selectors and fields are known, the script should filter directly and return only the needed data. If selectors aren’t known yet, the model can be used once to extract the relevant CSS class selectors and field mappings (titles, URLs, scores, comment counts, etc.), after which the scraper can run deterministically with far less repeated context.

The best-performing pattern described treats skill.md as an orchestrator while scripts do the heavy lifting. Scripts should output in model-friendly formats—typically JSON (or markdown when appropriate)—and ideally enforce a strict output schema in code. For multi-site scraping, the schema should at least normalize comparable fields like product name, URL, price, and discount.

Efficiency also depends on operational controls: run tasks in parallel using threads or batching to avoid sequential round trips, set explicit limits and stop conditions to prevent runaway pagination, and support incremental runs by checking prior saved reports and scraping only what’s new. Finally, hardcode stable parameters in scripts—such as proxy settings and known categories or usernames—so the model isn’t spending tokens on decisions that code can handle. The throughline is deliberate token management: decide what enters the context window, what leaves it, and what should never touch it—especially when token costs are a recurring business expense.