Why Didn't My Skill Update Save?

Last updated: April 7, 2026

Skill edits are saved at the end of a completed agent turn. If the save is skipped — due to invalid frontmatter, a name mismatch, a concurrent edit from another conversation, or an interrupted session — the previous version of the skill stays intact.

How Skill Saving Works

When the agent finishes responding to your message, the platform checks every skill directory in the sandbox and saves any changes back to the database. For each skill, it:

  1. Reads the SKILL.md file and parses the frontmatter

  2. Validates the name and description

  3. Checks that the name in frontmatter matches the directory name

  4. Compares a hash of the current files against the hash from when the skill was loaded — if nothing changed, the save is skipped

  5. If the skill changed and passes validation, it's saved to the database

If any step fails, that skill's update is silently skipped and the previous version remains. The rest of the conversation continues normally.

Cause 1: Invalid SKILL.md Frontmatter

The most common cause. If the agent edits the SKILL.md and accidentally breaks the YAML frontmatter, the save is skipped entirely.

What can go wrong:

  • Missing or empty name field

  • Missing or empty description field

  • Malformed YAML (e.g., a colon in the description without quotes, incorrect indentation)

  • Description contains angle brackets (< or >)

  • Name doesn't follow the naming rules (lowercase, hyphens only, max 64 chars)

How to fix: Ask the agent to check and fix the skill: "Read the SKILL.md for [skill-name] and make sure the frontmatter is valid YAML with a name and description."

Cause 2: Name/Directory Mismatch

The name field in SKILL.md must exactly match the directory the skill lives in. If the agent renames the skill in frontmatter but doesn't rename the directory (or vice versa), the save is skipped.

Example: Directory is /home/user/skills/email-outreach/ but the SKILL.md says name: outreach-playbook. This mismatch causes the save to be silently skipped.

How to fix: Ask the agent: "Check if the skill name in SKILL.md matches the directory name for [skill-name], and fix any mismatch."

Cause 3: Concurrent Edits (Two Conversations Editing the Same Skill)

If two conversations are open at the same time and both edit the same skill, the platform uses a hash-based comparison to handle this:

  • When a skill is loaded into a conversation's sandbox, a hash of its files is stored (in a hidden .skill_hash file).

  • When the conversation ends and tries to save, the current hash is compared to the original hash.

  • If the hash hasn't changed (meaning the agent didn't actually modify the files), the save is skipped — this prevents overwriting changes made by the other conversation.

  • If the hash has changed in both conversations, the last conversation to finish wins and overwrites the other's changes.

What this means in practice:

  • If only one conversation edits the skill, it saves normally.

  • If both conversations edit the skill, the one that finishes last overwrites the other.

  • There is no merge, no conflict resolution, and no warning.

How to avoid: Don't edit the same skill from multiple conversations at the same time. If multiple people have Editor access to the same agent (via sharing or a team), coordinate who is updating which skills.

Cause 4: Conversation Ended Abnormally

Skill edits are saved at the end of a completed agent turn. If the conversation is interrupted before the agent finishes responding — for example, you close the browser tab, the session times out, or there's a platform error — any skill changes made during that turn may not be saved.

How to fix: Check the skill in the Skills section. If the changes are missing, re-apply them in a new conversation.

Cause 5: Skill Editing Is Disabled

If the Skill Editing & Creation toggle is turned off in the agent's Tools configuration, the entire save flow is skipped — even if the agent modifies skill files in the sandbox during the conversation. The agent can still read and use skills, but nothing it writes will be saved.

How to check: Open the agent link → Skills → look for the Skill Editing & Creation toggle.

How to Verify a Skill Saved Correctly

After asking the agent to update a skill, you can verify the change was saved:

  1. Go to the Skills page

    1. Or scroll to the skills section of your agent

  2. Find the skill and click on it to preview the files

  3. Check that the content reflects the changes you asked for

Tips for Reliable Skill Updates

  • Be explicit: Instead of "update the skill," say: "Update the email-outreach skill to add a follow-up step after the initial email. Show me the updated SKILL.md before saving."

  • Ask to validate: After an edit, say: "Run the skill validator on [skill-name] to make sure it's valid." The agent can run python3 /home/user/skills/.tools/quick_validate.py [skill-name].

  • One conversation at a time: Avoid editing the same skill from multiple conversations simultaneously.

  • Check the result: After important updates, verify the skill content on the Skills page or in a new conversation.

Related Docs

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.