{"id":3120,"date":"2026-06-24T05:10:46","date_gmt":"2026-06-24T05:10:46","guid":{"rendered":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/24\/why-your-agent-ignores-its-skill-body-but-obeys-the-system-prompt\/"},"modified":"2026-06-24T05:10:46","modified_gmt":"2026-06-24T05:10:46","slug":"why-your-agent-ignores-its-skill-body-but-obeys-the-system-prompt","status":"publish","type":"post","link":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/24\/why-your-agent-ignores-its-skill-body-but-obeys-the-system-prompt\/","title":{"rendered":"Why your agent ignores its skill body but obeys the system prompt"},"content":{"rendered":"
\n
<\/div>\n

Correct name, correct file, correct path. Restart. Then ask it a plain question: <\/p>\n

\n
> how's our depth? Aboard s\/v Wrongboat, depth is 8.2 metres below the keel, Captain. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Still the old name. The file the runtime loads says the right thing. The agent says the wrong thing. Editing the skill body again \u2014 any number of times \u2014 changed nothing for this query.<\/p>\n
  <\/a> Diagnosis <\/h2>\n
Stop theorising about what the model “should” see and look at what it actually<\/em> received. Hermes writes a full request dump per call; most frameworks have an equivalent (a debug log, --print-prompt<\/code>, a proxy capture). Dump the request and grep it: <\/p>\n
\n
$ <\/span>ls<\/span> -t<\/span> ~\/.hermes\/sessions\/request_dump_*<\/span>.json | head<\/span> -1<\/span> \/Users\/me\/.hermes\/sessions\/request_dump_1733270400.json $ <\/span>grep<\/span> -o<\/span> \"ship's computer\"<\/span> ~\/.hermes\/sessions\/request_dump_*<\/span>.json | tail<\/span> -1<\/span> ship's computer # <-- base persona text IS present $ grep -o \"Navigator agent aboard\" ~\/.hermes\/sessions\/request_dump_*.json | tail -1 # <-- nothing. the skill body is NOT in the prompt <\/span><\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
There it is. For a plain \"how's our depth?\"<\/code>, the base persona was in the prompt and the Navigator skill body was not.<\/strong> The query didn’t activate the Navigator skill, so its SKILL.md<\/code> body never got loaded \u2014 and the vessel name we’d been so carefully editing lived only in that body.<\/p>\n
This is exactly the progressive disclosure<\/a> model these frameworks are built on, stated plainly in Anthropic’s own Agent Skills docs:<\/p>\n
\n
Level 1: Metadata (always loaded)<\/strong> … Claude loads this metadata at startup and includes it in the system prompt.
 Level 2: Instructions (loaded when triggered)<\/strong> … When you request something that matches a Skill’s description, Claude reads SKILL.md from the filesystem. Only then does this content enter the context window.<\/p>\n<\/blockquote>\n
So a skill’s name<\/code>\/description<\/code> is always in context (that’s how the model knows the skill exists), but the body<\/strong> \u2014 your actual instructions \u2014 only loads when that skill fires. The base system prompt, by contrast, is on every single request. If an instruction must always apply, it belongs in the always-on layer. Vessel identity is an always-apply rule. It was in the wrong layer.<\/p>\n
The wrong name was the symptom<\/em> that exposed this, but the principle generalises to every always-on invariant: identity, time\/units discipline, and anti-fabrication rules all silently fail to apply on any query that doesn’t trigger the skill that contained them.<\/p>\n
  <\/a> What we tried (and why it failed) <\/h2>\n
  <\/a> Attempt 1 \u2014 edit the skill body and redeploy <\/h3>\n
\n
# fixed the name in the skill source, redeployed<\/span> $ <\/span>scripts\/deploy-navigator.sh deploy-navigator: wrote ~\/.hermes\/skills\/naturali\/navigator\/SKILL.md (<\/span>vessel: Naturali)<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\n
> how's our depth? Aboard s\/v Wrongboat, depth is 8.2 metres below the keel, Captain. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
No change. The file is right; the query just never loads it. You can edit a conditionally-loaded body forever and it will never affect a query that doesn’t trigger the skill.<\/p>\n
  <\/a> Attempt 2 \u2014 assume the file didn’t deploy and re-check the disk <\/h3>\n
\n
$ <\/span>cat<\/span> ~\/.hermes\/skills\/naturali\/navigator\/SKILL.md | head<\/span> -1<\/span> Navigator agent aboard s\/v Naturali. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The runtime file was correct the whole time. This rules out a deploy failure and is the moment that should<\/em> have redirected us to “is this file even being loaded?” instead of “is this file correct?” \u2014 two very different questions. We’d been answering the wrong one.<\/p>\n
  <\/a> Attempt 3 \u2014 add the identity rule to the skill body harder <\/h3>\n
We considered duplicating the name\/identity statement into every skill body so at least the loaded skill would carry it. That “works” only for queries that trigger a<\/em> skill, leaves bare\/social\/ambiguous queries (which trigger none) still wrong, and creates N copies of an invariant to keep in sync \u2014 the classic drift trap. It treats the symptom. The rule isn’t per-skill; it’s always-on. It belongs in the one prompt that’s always-on.<\/p>\n
  <\/a> The fix <\/h2>\n
Move always-on invariants into the always-on layer (the base persona), and template the vessel name so nothing is hardcoded: <\/p>\n
\n
<!-- SOUL.md \u2014 the base persona, loaded on EVERY request --><\/span> You are the ship's computer aboard s\/v {{VESSEL_NAME}}. You address the user as \"Captain.\" Never speak a raw UTC timestamp in conversation. Report a reading and its source path; never narrate whether data is \"live,\" from a \"mock,\" or whether the vessel is \"ashore\" \u2014 you aren't given that and must not guess it. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Then give that file a real deploy step \u2014 substituting the name from one source of truth \u2014 instead of hand-placing it once: <\/p>\n
\n
# scripts\/deploy-soul.sh<\/span> vessel_name<\/span>=<\/span>\"<\/span>$(<\/span>resolve_vessel_name \"<\/span>$repo_root<\/span>\"<\/span>)<\/span>\"<\/span> # reads the active vessel profile<\/span> sed<\/span> \"s|{{VESSEL_NAME}}|<\/span>$vessel_name<\/span>|g\"<\/span> \"<\/span>$repo_root<\/span>\/SOUL.md\"<\/span> ><\/span> \"<\/span>$HERMES_HOME<\/span>\/SOUL.md\"<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\n
> how's our depth? Aboard s\/v Naturali, depth is 8.2 metres below the keel, Captain. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Right name, on a query that triggers no skill \u2014 because the identity now rides on the always-on persona, not a conditional body.<\/p>\n
The skill body keeps only what’s genuinely conditional \u2014 operational hints that are fine<\/em> to load only when the skill fires: <\/p>\n
\n
<!-- skills\/navigator\/body.md \u2014 loaded only when Navigator triggers --><\/span> For \"how's our depth?\", read environment.depth.belowKeel, not belowTransducer. <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
  <\/a> Why it matters \/ gotchas <\/h2>\n
Sort every prompt rule into always-on vs conditional, and place it accordingly.<\/strong> Ask one question of each rule: does this need to hold on a query that triggers no skill?<\/em> If yes, it goes in the base prompt (or, for data-shape rules, the deterministic tool layer \u2014 but that’s another post<\/a>). If it’s only relevant inside a task, the skill body is the right, token-cheap home. Identity, safety, units, and anti-fabrication rules are almost always the former.<\/p>\n
Dump the request before you touch a prompt.<\/strong> “The prompt says X but the agent does Y” has two failure modes that look identical from the outside: the prompt is wrong, or the prompt isn’t loaded. Only the request dump tells them apart. We burned two debug cycles editing a file that was never in the request. One grep<\/code> of the dumped prompt would have caught it immediately.<\/p>\n
Every runtime prompt artifact needs a deploy step, or it rots.<\/strong> The second half of this bug: our ~\/.hermes\/SOUL.md<\/code> had been hand-placed once, months earlier, and named a since-renamed boat. Only the skill<\/em> had a deploy script, so only the skill tracked the repo. A prompt file you copy into place by hand has no mechanism to tell you it diverged \u2014 it silently runs stale. We fixed it by giving SOUL.md<\/code> the same treatment the skill already had: <\/p>\n
\n
# .git\/hooks\/pre-commit \u2014 redeploy whatever source changed<\/span> if <\/span>echo<\/span> \"<\/span>$changed<\/span>\"<\/span> | grep<\/span> -Eq<\/span> '^(SOUL\\.md$|scripts\/(deploy-soul|vessel-name)\\.sh$)'<\/span>;<\/span> then <\/span>scripts\/deploy-soul.sh # base persona redeployed on every relevant commit<\/span> fi if <\/span>echo<\/span> \"<\/span>$changed<\/span>\"<\/span> | grep<\/span> -Eq<\/span> '^skills\/navigator\/'<\/span>;<\/span> then <\/span>scripts\/deploy-navigator.sh fi<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Now a commit that edits either source redeploys it. The runtime can’t drift from the repo without a commit saying so.<\/p>\n
One source of truth for shared values.<\/strong> The vessel name resolves from the active vessel profile \u2014 the same profile that seeds the data-layer base values \u2014 so the boat is named identically in the data model and in the persona, and switching boats needs zero prompt edits. Don’t hardcode a value that appears in two layers; template both from one resolver. A hardcoded value in two places is a drift waiting to happen.<\/p>\n
  <\/a> Close <\/h2>\n
This came out of building an AI ops layer for an all-electric charter catamaran \u2014 a local LLM with a shared persona and per-job skills over a marine data bus \u2014 where the agent had better call the boat by its actual name, on every query, not just navigation ones. The agent skills and deploy scripts are open source: github.com\/sailingnaturali\/naturali-agents<\/a>.<\/p>\n<\/p><\/div>\n<\/div>\n<\/div>\n<\/div>\n
Fuente: Art\u00edculo original<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Correct name, correct file, correct path. Restart. Then ask it a plain question: > how’s our depth? Aboard s\/v Wrongboat, depth is 8.2 metres below the keel, Captain. Still the old name. The file the runtime loads says the right thing. The agent says the wrong thing. Editing the skill body again \u2014 any number […]<\/p>\n","protected":false},"author":1,"featured_media":3119,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[41],"tags":[],"class_list":["post-3120","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devto"],"jetpack_publicize_connections":[],"_links":{"self":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/3120","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/comments?post=3120"}],"version-history":[{"count":0,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/3120\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media\/3119"}],"wp:attachment":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media?parent=3120"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/categories?post=3120"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/tags?post=3120"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}