Skip to content
Hidden Logic Lab

Audit agent skill folders for SKILL.md casing on Linux CI

Cursor and Claude Code only load a skill when the file is exactly SKILL.md. An agent skill audits skill directories on Linux runners and fixes silent Unknown skill failures from skill.md or Skill.md.

·Coding·25 min·Working

A casing-audit SKILL.md in the repo, a CI or pre-commit check that fails on wrong filenames, and every skill folder discoverable on case-sensitive filesystems.

  1. 1

    Run the audit on Linux first

    Reproduce on ubuntu-latest or your cloud agent image. macOS-only green gives false confidence.

  2. 2

    Add a one-line CI gate

    A 10-line find/git check beats a quarterly manual audit. Fail the job on wrong casing before merge.

  3. 3

    Document skill roots in AGENTS.md

    One bullet listing .cursor/skills and any Claude Code path so contributors do not add a third layout.

The prompt to paste

Write SKILL.md for auditing agent skill folders so skills load on Linux CI and cloud agents. Cursor and Claude Code look for exactly SKILL.md — not skill.md, Skill.md, or README-only folders.

Repository context:
[skill roots: e.g. .cursor/skills/, .claude/skills/, docs/agent-skills/]
[CI OS: ubuntu-latest or other Linux runner where the agent runs]
[how skills are referenced: AGENTS.md, CLAUDE.md, project rules]

SKILL.md must include:
1. Purpose — skills that work on a Mac developer laptop must also load on Linux CI; wrong casing fails silently or shows "Unknown skill."
2. When to use — adding or moving skills, onboarding a repo to agents, or debugging "skill not found" on CI only. When not to use — editing skill body text when the filename is already correct.
3. Required filename rules (non-negotiable):
   - Entry file must be named exactly SKILL.md (all caps SKILL, .md lowercase).
   - Optional companion files: references.md, scripts/ — but no alternate entry names like skill.md or SKILL.MD.
   - Folder name is the skill id; do not rely on display title in YAML front matter alone if the client reads the path.
4. Audit steps the agent must run and report:
   - List every directory under each skill root (recursive, max depth [confirm — often 2]).
   - For each folder intended to be a skill, verify SKILL.md exists with exact casing (use git ls-files or find — case-sensitive).
   - Flag: skill.md, Skill.md, SKILL.MD, skills.md, or skill content only in README.md without SKILL.md.
   - Flag: duplicate skill names differing only by case in path segments.
   - Flag: symlinks or macOS resource forks that disappear on Linux [note if N/A].
   - Check AGENTS.md / CLAUDE.md links: hrefs and @-aliases must match folder names on disk.
5. Fix protocol:
   - Rename with git mv (preserves history): git mv skill.md SKILL.md — never duplicate both.
   - Update any doc links that pointed at the old name.
   - Re-run audit until zero casing findings.
6. CI hook pattern (describe, do not invent exotic tools):
   - A shell step or lint script that exits 1 if find finds */skill.md or missing SKILL.md in declared skill dirs.
   - Paste example script skeleton using only bash/find/git — no network.
7. Two example prompts: "CI says unknown skill for deploy-checklist" vs "new contributor added .cursor/skills/foo/skill.md."
8. Pitfalls: fixing only local case-insensitive FS, committing both skill.md and SKILL.md, renaming without updating AGENTS.md aliases, assuming Claude Code and Cursor share the same skills root path.
9. Done means: audit table (path, status OK|FIXED|BLOCKED), all skill dirs contain exactly SKILL.md, CI check documented or added, links in AGENTS.md verified.

Rules:
- Use real paths from repo context; [confirm path] if unknown.
- Do not run chmod or execute skill scripts during audit unless human asks.
- Output only SKILL.md markdown.

Git on Windows can hide casing-only renames. Use git mv and verify with git ls-files on a Linux runner, not only locally.

Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.