Designing Coding Agent Skills That Actually Work

I've spent the last few months obsessed with AI coding agents. Not just using them. Building alongside them and optimizing them for my use-cases. I've designed and tested various skills for agents like Claude Code, VScode Copilot, Codex, and Cursor, and I've watched closely to see where they hold up and where they quietly fall apart.

And they do fall apart. Usually in the same way. The agent does great for three steps, then does something dumb on step four, it starts backtracking and analyzing went wrong, and by the time it figures out the issue, the conetxt window is almost full, leaving you with 3 what-have-I-done-so-far.md files instead of a task done.

After enough of those moments, I stopped trying to make the agent smarter. I changed how I think about skill design entirely. This blog is about that shift, and the patterns that came out of it.

The skill that taught me this

The example I keep coming back to is a skill I built called confluence-publisher. The origin is boring but honest: I didn't have corporate access to a Confluence MCP server, so my agent had no native way to publish pages. Instead of waiting on IT, I built the bridge myself: a skill that takes markdown and publishes it to Confluence.

I used this skill design as my sandbox for my new skill framework. Every pain point I'd hit with other skills showed up here too, so I used it to work out what actually makes an agent skill reliable. The full code is on GitHub if you want to follow along:

🔗 GitHub:

The most important choice in the whole design: the agent doesn't write code at runtime. It runs pre-written scripts and decides with the correct context.

Each step in the workflow is a standalone Python script — step_01_convert.py, step_02_publish.py — with a clean interface, just like any tool in the agent's toolkit. CLI arguments go in, structured output and exit codes come out. The agent's job shrinks to four things:

1. Decide what arguments to pass


2. Run the script


3. Read the output


4. Decide what to do next

That removes the ambiguity. Instead of asking the model to reason about Confluence API semantics, authentication, HTTP headers, and XHTML formatting on the fly, the scripts hold all that complexity. The agent only has to understand the contract: what goes in, what comes out.

In my tests, even a non-reasoning model like GPT-4o follows this without getting lost, because the SKILL.md reads like a recipe. Set your variables, run step 1, check the output, run step 2. There's no open-ended problem-solving at runtime, so there's very little room to improvise a mistake.

Failures that speak up

One of the hardest problems in agentic workflows is the context window. A 16,000-character HTML document doesn't need to live in the agent's memory. It just needs to be reachable.

The artifacts/ folder handles that:

• Step 1 converts markdown to XHTML and writes it to artifacts/{Title}_{RUN_TS}.html
  


• Step 2 reads from that file path


• The agent only holds the path, never the content

So the agent can move large documents through the workflow without burning context. It can also inspect an artifact between steps if needed (ex. read the HTML to check the conversion looks right before publishing). The naming convention ({Title}_{RunTimestamp}.html) makes each artifact self-describing, so if a run does something weird weeks later, you can find the exact file from that run.

Work-logs as governance

Credentials should not be exposed to the agent context window. The authentication should be done programatically and preferably from a service account designed for the agnet itself. The credentials can be read from secret managers and perform authentication aside from the agent's context. In this example, I am using a .env file that is not tracked on git for simplicity of demo. The scripts load the credentialls internally through _load_env_file(). The agent never sees the token value in its context.

CODE Kopieren

def _load_env_file() -> None:

    """Load variables from the skill's .env file into os.environ."""

    env_path = Path(__file__).resolve().parents[1] / ".env"

    ...

    for line in f:

        key, _, value = line.partition("=")

        if key and key not in os.environ:

            os.environ[key] = value

The scripts are designed to check for required variables to be set and if they cannot identify them then a "Missing environment variables: CONFLUENCE_API_TOKEN" error would notify the agent.

A .template-env file shows the expected shape without real values:

CODE Kopieren

CONFLUENCE_URL=https://your-company.atlassian.net

CONFLUENCE_EMAIL=your-company-email

CONFLUENCE_API_TOKEN=developer-api-token-get-from-confluence-site

The human operator manages the secrets, and the agent runs with whatever permissions the authenticated app already has. No OAuth flows, no token rotation for the agent to reason about. It just operates in the sandbox that is allowed to access.

Design for the floor, not the ceiling

As you notice, the thread running through all of this is that SKILL.md is written in a way to reduce confusion so that a model without chain-of-thought reasoning can also run it correctly. A few techniques make that work:

• 
  Numbered steps with exact commands. The agent doesn't figure out how to call a script — the exact command is right there with placeholder variables marked clearly.


• 
  One decision per step. Each step has one outcome to check (the exit code) and one branch to take (continue or stop).


• 
  No nested logic. There's no "if the page exists and the mode is upsert and the parent changed, then..." Each mode is independent, and the script handles its own logic.


• 
  Structured output. Scripts print JSON on success, so any model can parse the result without extra parsing logic.

This is a deliberate tradeoff. A stronger model could handle a messier interface, but by designing for the floor, the skill works across model tiers (even local models that run on the consumer devices).

When to reach for this (and when not to)

A fair question for this audience: if MCP exists, why build a skill out of scripts at all? I started here because I didn't have MCP access, but the two aren't really competitors. An MCP server hands the agent a set of tools. This pattern hands the agent an ordered recipe, plus on-disk memory and an audit trail of what it did. You can even run both, and point the recipe at MCP tools instead of local scripts.

The honest tradeoff: this works best for workflows that are mostly linear and have real side effects you want recorded. Publish, deploy, migrate, generate-and-ship. It's a poor fit when the work is exploratory or needs the agent to branch in ways you can't predict ahead of time. Pre-written scripts can't adapt to a situation you didn't script for, and writing them is upfront cost. If a task is a one-off, skip the ceremony and let the agent improvise. The moment it becomes something you'll run again and you care about the outcome, the structure pays for itself.

Wrapping up

If I had to compress everything I learned into one line: don't make the agent smarter. Make its tools more predictable. Let the agent reason about intent, and let deterministic scripts do the acting.

The same idea, broken down by what each piece does:

Principle	How it's applied
Remove ambiguity	Pre-written scripts with CLI contracts
Fail vocally	Specific exit codes + descriptive error messages
Manage context	Artifacts on disk, not in memory
Govern side effects	Work-logs capture every action with timestamps
Protect secrets	.env loaded by scripts, never surfaced to the agent
Design for simplicity	Linear steps, exact commands, structured output
Enable self-correction	Past logs readable by future runs

The result is a skill that a high-reasoning model can design, but a basic model can still operate. It runs predictably, and you can trace exactly what it did.

The full confluence-publisher code is here if you want to dig in or fork it:

🔗 GitHub: — I share what I learn as I keep building.

Regards,

Erfan

Vollständiger Original-Bericht

Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

↗ Original-Artikel auf dev.to lesen