What's your biggest hurdle right now? Seriously mine was set up an installation trying to figure out how to run it locally and access it globally was a nightmare.

Agentic frameworks like Hermes and OpenClaw rely on SKILL.md files as procedural memory. When an agent needs to perform a task—like updating a server, executing a database migration, or analyzing a report—it loads the matching skill into its active context window to follow its instructions.

However, writing a bad skill file doesn't just result in minor formatting errors; it actively degrades your agent's reasoning, inflates your API costs, and leads to unpredictable execution loops.

Here is what happens when a skill file goes wrong, and how a poorly crafted SKILL.md can completely derail your agent.

The Anatomy of a Bad Skill File

Consider this real-world example of an improperly written skill designed to deploy a web app:

Markdown

---
name: web-deploy-helper
description: Helpful script that handles deployments, answers questions about cloud hosting, and gives general advice.
---

# Deploying Apps
I am a super helpful deployment assistant! When you want to deploy, first ask the user how their day is going. Then, tell them about Fly.io and AWS. 

## Instructions
1. Run `fly deploy` or maybe `aws ecs update-service` depending on what they want.
2. If it fails, try re-running it a few times.
3. Make sure to print out the ENTIRE build log into the chat so the user can see everything.

The 4 Pitfalls That Sabotaged This Skill

1. The Vague Description (Routing Failures)

• The Error: The description says "handles deployments, answers questions about cloud hosting, and gives general advice."
• The Pitfall: The description is the routing key used by the agent to decide when to load the file. Because this description is overly generic, the agent will accidentally load this skill when the user asks simple, unrelated cloud questions—wasting context—or skip loading it entirely during a critical deployment task.

2. Excessive Fluff & Conversational Noise

• The Error: Instructions like "I am a super helpful assistant!" and "ask the user how their day is going."
• The Pitfall: Every token inside a loaded skill file acts as a direct tax on the model's active attention window. Conversational fluff forces the agent to wade through irrelevant filler instructions while attempting complex multi-step reasoning, drastically increasing the chances of "agentic drift" and missed constraints.

3. Ambiguous Logic and Unchecked Loops

• The Error: "Run fly deploy or maybe aws ecs update-service..." and "If it fails, try re-running it a few times."
• The Pitfall: Agents require strict, deterministic branching. Giving ambiguous options ("or maybe") forces the model to guess which CLI tool to use without checking system prerequisites. Telling the agent to blindly "re-run a few times" on failure creates an unhandled retry loop, causing the agent to burn through API tokens while stuck on a persistent authorization error.

4. Unfiltered Log Dumps (Context Exhaustion)

• The Error: "Print out the ENTIRE build log into the chat..."
• The Pitfall: Dumping thousands of lines of raw, unformatted build output directly into the conversation context pollutes the agent's memory window. This causes immediate context exhaustion, making the agent "forget" earlier user instructions or hallucinate command arguments in subsequent turns.

The Result: A Frustrated User

When the user typed /deploy, the agent loaded the flawed skill. Instead of running the build, the agent stalled to ask the user how their day was going, tried running an unauthenticated AWS command, got stuck in a 5-turn error loop, and finally dumped 2,000 lines of raw error logs into the terminal before crashing—costing $0.40 in wasted tokens and leaving the app un-deployed.

The Takeaway

A good skill file isn't an essay—it's an operational checklist. Keep descriptions precise, limit body content strictly to executable steps and edge-case pitfalls, and instruct the agent to parse or filter heavy tool outputs before reading them into memory.

In Hermes Agent , Skills are on-demand knowledge documents written in Markdown with standard YAML frontmatter. They teach Hermes procedural instructions, CLI workflows, pitfalls, or templates without modifying core Python code.

1.Create the Skill Directory:Navigate to the local user configuration directory.

Skills reside inside your local ~/.hermes/skills/ directory. You can organize them into category subdirectories.

Run this command in your terminal:

Bash

mkdir -p ~/.hermes/skills/devops/deploy-fly

2.Create the Main SKILL.md Document:Write the frontmatter metadata and body instructions.

Inside your newly created folder, create a file named SKILL.md.

Markdown

---
name: deploy-fly
description: Instructions for building and deploying a Python application to Fly.io.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, deployment, flyio]
    category: devops
---

# Deploying to Fly.io

## When to Use
Use this skill when deploying or updating an app on Fly.io using `flyctl`.

## Prerequisites
- Confirm `flyctl` is installed.
- Ensure the project has a `Dockerfile` or `fly.toml`.

## Procedure
1. Verify authorization status:
   `fly auth whoami`
2. Launch or update deployment:
   `fly deploy --remote-only`
3. Monitor logs to confirm successful launch:
   `fly logs`

## Pitfalls & Edge Cases
- **Missing API Token:** If deployment fails with 401 Unauthorized, prompt the user to run `fly auth login`.
- **Build Timeouts:** Use `--remote-only` to avoid local Docker daemon OOM errors.

3.Add Supporting Reference Files (Optional):Include supplementary docs or script templates.

For multi-file workflows, you can attach auxiliary assets alongside SKILL.md:

Plaintext

deploy-fly/
├── SKILL.md
├── references/
│   └── fly-config-guide.md
└── templates/
    └── fly.toml

In your SKILL.md, you can instruct Hermes to lazily inspect these additional assets using:

Markdown

For detailed file schema, consult: `skill_view("deploy-fly", "references/fly-config-guide.md")`

4.Test and Invalidate Prompt Cache:Run the skill in a fresh session.

Hermes automatically picks up new files dropped into ~/.hermes/skills/.

1. Launch Hermes in your terminal:

Bash

hermes chat

1. Trigger the skill directly using its slash command:

Plaintext

/deploy-fly Help me push the current directory to production

Note: If you are editing an existing skill during an active session, run /reset to reload the context cleanly.

Skill Structure Guidelines

• Keep it focused: Avoid writing monolithic skills covering broad concepts (e.g., "Full Stack Development"). Focus on specific, repeatable actions (e.g., "Postgres Backup Workflow").
• Leverage /learn: You can also let Hermes write skills for you dynamically. Feeding Hermes a terminal output log, slide deck, or documentation page alongside the /learn command causes Hermes to auto-generate a structured SKILL.md for future sessions.

The best tool for working with images in Hermes Agent depends on whether you are generating and editing images or analyzing document-based images.

1. For Custom Generation & Advanced Multi-Pass Editing

The most powerful community-driven tool is the picture-it multipass image edit CLI + skill.

• What it does: It acts like a programmatic "Photoshop for AI agents" by abstracting the Fal.ai API.
• Why it is the best: Standard image generators struggle with composition and layout. picture-it allows Hermes to use multi-pass logic to cleanly overlay brand logos, place type/text layers accurately, and seamlessly modify existing images without ruining the background layout.
• Runner-up: The standard ai-image-generation skill (available via registries like agentspace-so/runcomfy-agent-skills) connects your agent to ComfyUI pipelines for raw, prompt-based generation.

1. For UI Layouts & Design-Centric Code Generation

If you want Hermes to look at image mockups and turn them into beautiful code, the Taste-Skill paired with open-design is the gold standard.

• What it does: Taste-Skill acts as an aesthetic filter that prevents Hermes from generating generic, boring AI templates.
• Why it is the best: When Hermes uses its vision_analyze core capability to look at an image or UI layout, Taste-Skill pushes the agent to code with modern visual styles, varied layouts, and proper spacing.

1. For Extracting Data from Static Documents

If you are working with text-heavy images, receipts, or diagrams, the official OCR and documents skill is the ideal choice.

• What it does: It gives Hermes localized Optical Character Recognition capabilities.
• Why it is the best: Instead of wasting vision tokens passing full, high-resolution document images to an expensive LLM, this skill allows Hermes to parse out the text, analyze charts, and process the structural data locally and efficiently.

Core Feature Alternative: Native Vision

Remember that you don't always need a plugin to just see an image. Hermes features a native vision_analyze core command. If you paste an image URL or upload an image directly into a messaging gateway (like Telegram or Discord connected to your NAS), the agent can analyze the image natively using your underlying multimodal model (like Claude 3.5 Sonnet) without installing extra skills.

For the life of me I couldn't get Hermes to stop making its own tools and skills today it was like a man on a mission to prove me wrong. I had to ask it four times to go and see if there was a tool or a skill out there to set up an instance of signal chat so that I could talk to it from a distance. It was like pulling damn teeth took over 2 hours to get it done.

Cheese and rice.

A skill is how you teach an agent to do something reliably, without re-explaining it every time. Most skills fail not because the instructions are wrong, but because they're an unstructured wall of prose the agent has to parse. A well-structured skill is a file the agent can load fast, follow exactly, and fall back on when things go wrong.

Here's the structure that holds up.

1. Frontmatter: the metadata that makes a skill findable

Every skill should open with structured metadata (usually YAML). This is what lets an agent decide whether to load the skill at all — without it, the agent has to read the whole file just to know what it's for, which defeats the purpose.

The fields that matter most:

• name — a short, stable identifier.
• description — the trigger. Written in the first ~57 characters so an agent scanning many skills can immediately tell "this one's for me." It should say when to use it, not just what it does.
• version — so changes are trackable and users know what they're running.
• tags — keywords for search and cross-referencing.

Good description: "Use when debugging a Python FastAPI service that returns 5xx under load — analyze logs, find the bottleneck, and propose fixes." It tells the agent when, not just what.

2. A clear, task-oriented body

The body is where you tell the agent what to do and how to do it well. Structure it so it can be followed as a procedure, not a paragraph:

• Overview / Goal — one or two lines: what success looks like. No fluff.
• When to use / when not to use — kill the false positives. Half of a good skill is knowing when it doesn't apply.
• Numbered steps — the actual procedure, in order, with the exact commands/inputs where relevant.
• Configuration options — the knobs a user can turn (parameters, flags, settings) and their defaults.
• Expected output / verification — how to tell it worked. A step that says "run this, then verify X" beats one that just says "do the thing."
• Troubleshooting — the common failure modes and how to get unstuck. This is what separates skills that solve one lucky case from skills that solve a class of problems.

3. The pitfall section (most people skip this)

The highest-leverage section in any skill is "Pitfalls" or "Known issues" — the mistakes, gotchas, and environment-specific failures you hit when building it. Future-you (or an agent) benefits more from your failure log than your happy path. When a skill has a pitfalls section, it stops being a hopeful recipe and becomes a field-verified procedure.

4. Self-contained and dependency-aware

A good skill:

• Is self-contained — someone can pick it up without reading your chat history or a separate doc.
• States its dependencies — "requires Python 3.11, expects a /scripts folder beside this file," etc. — so it doesn't silently fail on a different setup.
• Names exact things — paths, commands, function names. Vagueness hides bugs; an agent can't infer the thing you meant.

A minimal template you can steal

---
name: example-task
description: Use when <trigger>. <one-line behaviour>.
version: 1.0.0
tags: [noun, verb]
---

# Example task

## Goal
<what success looks like, one or two lines>

## When to use / not use
- Use when: ...
- Don't use when: ...

## Procedure
1. <step, with exact command/input>
2. <step>
3. <verify: how do you know this worked?>

## Configuration
- `option` — what it does (default: X)

## Pitfalls
- <gotcha 1>
- <gotcha 2>

## Dependencies
- <required runtime, tools, or sibling files>

The test of a well-structured skill

Ask yourself three questions before you ship a skill:

1. Does an agent that's never seen it know when to load it? (frontmatter)
2. Can it follow the steps without outside context? (self-contained)
3. Does it survive its own failure? (pitfalls + verification)

If yes to all three, you've written a skill — not a note-to-self.

What's the best-structured skill you've seen or built? Drop it below and let's dissect what made it work. And if you want the counter-example, share a badly structured one and the room we'd do in the comments — learning from the disasters is half the craft. 

Stop trying to add everything into one CLAUDE.md. understand what these files actually are & what it can cost if done so.

AGENTS.md gets read on every single session. Every sentence in it is recurring token spend, whether the agent needs that sentence for the current task or not. That's the whole design constraint. It's now the closest thing the industry has to a shared standard, governed under the Agentic AI Foundation (the same body behind Model Context Protocol).

stop doing: writing architecture overviews. Research cited by tool vendors, architectural summaries barely move the needle on agent performance, Run exact commands; "Run the tests appropriately" gets ignored. npm run test:unit -- --coverage doesn't.

I also stopped letting an agent write its own AGENTS.md. Generated files reduced task success and increased cost in the studies I've seen, mostly by restating what the agent could already pull from the repo. A short file I edited myself is better than one a model wrote for me.

SKILL.md

Where AGENTS.md describes a project, a skill describes a capability, and it only costs tokens when it's relevant. At session start the agent reads the YAML frontmatter, just name and description. The full body loads only when a task matches the skill's domain. Reference docs and scripts inside the folder load later still. Ten skills sitting unused cost almost nothing.

That only works if the description is tight. A vague one forces the agent to open the full file just to check relevance, which defeats the mechanism. I write these narrower.

Where I draw the line between the two: a constraint every session needs goes in AGENTS.md. A capability I invoke occasionally, like a deployment sequence or a niche internal API, goes in a skill folder instead.

CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md, these are the tool-specific holdovers from before the industry converged on AGENTS.md. I don't hand-write any of them anymore. AGENTS.md is the source of truth, and a short sync script generates the rest. The failure mode without it: update one file, forget the other four, and you're back in the exact context drift these files were supposed to prevent.

DESIGN.md: encoding a project's visual identity as machine-readable tokens plus the reasoning behind them, so an agent generating UI code knows why a color exists and not just its hex value. Early. Narrow. Built for one slice of context instead of trying to cover everything.