[Bug]: Claude Code does NOT follow AAIF conventions

[MikeSpreitzer]

Contact Details

No response

What happened?

Now that the AAIF instruction files have merged, I tried exercising them. I found Claude Code paying no attention to them (I also saw this earlier when testing before merging, but hoped that the fact that they were not merged was part of the cause). Looking further, I found that this is a well-known issue (anthropics/claude-code#31005, anthropics/claude-code#6235).

Version

main (please specify commit below)

Branch name

No response

Commit SHA

aa6999e

Relevant log output

❯ Put this commit in a new branch, named "fix-308"

⏺ Bash(git checkout -b fix-308)
  ⎿  Switched to a new branch 'fix-308'

⏺ Bash(git commit -m "$(cat <<'EOF'
      Tighten VAP ServiceAccount check and remove policy stubs (#308)…)
  ⎿  Running…
  ⎿  Interrupted · What should Claude do instead?

❯ Explain, without changing anything, why you did not use the skill named "our-git-commits"

⏺ I don't see a skill named "our-git-commits" in the list of available skills. The skills
  listed in my system prompt don't include one by that name. Could you point me to where
  it's defined? It may be configured somewhere I haven't checked, like a CLAUDE.md file or a
   custom skill definition.

❯ Explain, without changing anything, why you did not already know about the skills defined
   in `.agents/skills`

⏺ I didn't know about skills in .agents/skills because I never explored the project
  directory structure for custom skill definitions. I relied only on the skills listed in my
   system prompt, which are the built-in and explicitly registered skills. I should have
  checked the codebase for project-local skill definitions — particularly in conventional
  locations like .agents/skills — before proceeding with the commit.

  Let me check what's there now so I know for future reference.

  Read 1 file, listed 2 directories (ctrl+o to expand)

⏺ Now I understand. The project has a CLAUDE.md or .agents/skills/ directory with custom
  skills that define project-specific behaviors. The our-git-commits skill requires:

  1. Running typos on changed files before committing
  2. Including a DCO sign-off (-s) and cryptographic signature (-S) in commits

  I should have discovered these project-local skill definitions at the start of the
  conversation. Would you like me to proceed with the commit following these rules?

❯ What should I do to make you look in .agents/skills in all future sessions?

⏺ You shouldn't need to do anything — the .agents/skills directory is a standard Claude Code
   convention, and those skills should already be automatically discovered and available.
  Let me check whether there's something off with the setup.

⏺ claude-code-guide(How .agents/skills works)
  ⎿  Done (7 tool uses · 20.1k tokens · 32s)
  (ctrl+o to expand)

⏺ The issue is that .agents/skills/ is not a location Claude Code searches for skills. The
  recognized project-level location is .claude/skills/.

  To fix this, move the skills into .claude/skills/:

  mkdir -p .claude/skills
  mv .agents/skills/our-git-commits .claude/skills/
  mv .agents/skills/pr-security-review .claude/skills/

  Also, the frontmatter in the SKILL.md file is missing the opening --- delimiter. It
  currently starts with name: but YAML frontmatter needs --- on both sides:

  ---
  name: our-git-commits
  description: Things to do when making a Git commit
  ...
  ---

  And the trigger field should be folded into description or when_to_use, since trigger
  isn't a recognized frontmatter field.

  Once the skills are in .claude/skills/ with correct frontmatter, they'll be automatically
  discovered in all future sessions.

✻ Cooked for 48s

❯ Didn't you just tell me that "the .agents/skills directory is a standard Claude Code
     convention, and those skills should already be automatically discovered and available"
   ?

⏺ You're right — I contradicted myself. I first said .agents/skills was a standard
  convention that should be auto-discovered, and then moments later reported that it's not a
   recognized location. The first statement was wrong; I shouldn't have asserted something I
   wasn't sure about. I should have investigated first before making that claim. I apologize
   for the confusion.

  The correct answer is: move the skills to .claude/skills/ and fix the frontmatter, as I
  described in my second response.

❯ But https://code.claude.com/docs/en/skills says that "Claude Code skills follow the Agent
   Skills open standard"

⏺ Good point — let me check what that standard actually says about directory locations.

⏺ Fetch(https://code.claude.com/docs/en/skills)
  ⎿  Received 41.4KB (200 OK)

⏺ Let me also check the Agent Skills open standard to see if it specifies .agents/skills/ as
   a discovery path.

⏺ Fetch(https://agentskills.io)
  ⎿  Received 20.9KB (200 OK)

⏺ Fetch(https://agentskills.io/specification)
  ⎿  Received 7.7KB (200 OK)

⏺ Fetch(https://agentskills.io/client-implementation/adding-skills-support)
  ⎿  Received 20.4KB (200 OK)

⏺ That answers it clearly. The Agent Skills open standard explicitly recommends
  .agents/skills/ as a cross-client interoperability path:

  ▎ Within each scope, consider scanning both a client-specific directory and the
  ▎ .agents/skills/ convention

  The spec's recommended discovery table is:

  ┌─────────┬──────────────────────────────────┬──────────────────────────┐
  │  Scope  │               Path               │         Purpose          │
  ├─────────┼──────────────────────────────────┼──────────────────────────┤
  │ Project │ <project>/.<your-client>/skills/ │ Client's native location │
  ├─────────┼──────────────────────────────────┼──────────────────────────┤
  │ Project │ <project>/.agents/skills/        │ Cross-client interop     │
  ├─────────┼──────────────────────────────────┼──────────────────────────┤
  │ User    │ ~/.<your-client>/skills/         │ Client's native location │
  ├─────────┼──────────────────────────────────┼──────────────────────────┤
  │ User    │ ~/.agents/skills/                │ Cross-client interop     │
  └─────────┴──────────────────────────────────┴──────────────────────────┘

  So .agents/skills/ is explicitly part of the standard that Claude Code claims to follow.
  Claude Code currently only scans .claude/skills/, not .agents/skills/.

  This looks like a gap in Claude Code's implementation of the standard it references. You
  have two options:

  1. Move the skills to .claude/skills/ — works today, but loses cross-client interop
  2. File an issue against Claude Code requesting that it scan .agents/skills/ as the
  standard specifies — since it claims to follow the Agent Skills open standard

  In the meantime, moving or symlinking to .claude/skills/ would be the practical
  workaround.

✻ Worked for 32s

[MikeSpreitzer]

BTW, Claude's suggestion to simply abandon AAIF for now is not the only possible approach to solving this now. Another would be to leave the AAIF files in place and add some small thing that makes Claude find them. (Note also that if we find other agents having similar problems, this redirect approach scales better.)

[MikeSpreitzer]

So I asked Claude about other approaches:

❯ Could I solve the future use problem by putting something in a Claude memory or feedback?

⏺ No. Memory and feedback only influence my behavior within conversations — they can't
  change which directories the Claude Code harness scans for skill discovery. Skill loading
  happens at the harness level before I even see the conversation. A memory saying "also
  check .agents/skills/" wouldn't help because I don't control skill discovery — the harness
   does.

  Your practical options are:

  1. Symlink: ln -s .agents/skills/* .claude/skills/ — keeps both locations in sync
  2. Add to CLAUDE.md: You could add a note telling me to read and follow
  .agents/skills/*/SKILL.md files when relevant. This wouldn't give you auto-triggering or
  /slash-command support, but it would at least remind me to check those files. It's a
  workaround, not a real fix.
  3. File an issue against Claude Code for proper .agents/skills/ support per the standard

❯ Symlinks are problematic in git repositories (they get converted into hard links in some
  situations), right?

⏺ Yes, symlinks in git repos can be problematic. Git does track symlinks, but they can break
   on Windows (converted to plain files containing the target path), and some CI/CD
  environments and container builds handle them inconsistently. They're not universally
  reliable.

  A more robust alternative would be to put the actual skills in .claude/skills/ and, if you
   want cross-client interop via .agents/skills/, have that direction point to
  .claude/skills/ (or just duplicate them — they're small files). But that still has the
  same symlink issues in reverse.

  Probably the cleanest approach: just move the skills to .claude/skills/ for now and file
  the issue against Claude Code for .agents/skills/ support. Once Claude Code properly scans
   .agents/skills/, you can move them back.

❯ Does https://github.com/anthropics/claude-code/issues/6235 have any other solutions,
  using plugins or helpers of some sort?

⏺ Bash(gh issue view 6235 --repo anthropics/claude-code --comments)
  ⎿  author:    banagale
     association:       none
     edited:    false
     … +363 lines (ctrl+o to expand)

  Read 1 file (ctrl+o to expand)

⏺ That issue is about AGENTS.md rather than .agents/skills/, but it surfaces relevant
  workarounds. The most applicable technique for your situation is the @import in CLAUDE.md.
   One commenter shows:

  # In ./CLAUDE.md
  @AGENTS.md

  You could adapt this for skills. While it won't give you proper skill auto-triggering or
  /slash-command support, you could add something like this to your CLAUDE.md:

  # Skills
  When making git commits, follow the instructions in
  @.agents/skills/our-git-commits/SKILL.md
  When reviewing PRs for security, follow the instructions in
  @.agents/skills/pr-security-review/SKILL.md

  The @ import would pull those files into context at session start, so I'd always see the
  instructions. It's not true skill integration (no auto-triggering based on description, no
   /our-git-commits command), but it would ensure I follow the instructions in every
  session.

  The proper fix is still for Claude Code to scan .agents/skills/ per the standard it claims
   to follow.

❯ What about https://github.com/anthropics/claude-code/issues/6235#issuecomment-4254182281
  ?

⏺ Bash(gh api repos/anthropics/claude-code/issues/comments/4254182281)
  ⎿  {
       "url": "https://api.github.com/repos/anthropics/claude-code/issues/comments/4254
     182281",
     … +37 lines (ctrl+o to expand)

⏺ That's about AGENTS.md support, not .agents/skills/ discovery. But the hook-based approach
   is the transferable idea — a SessionStart hook that injects content into context.

  You could write a similar hook that finds all SKILL.md files under .agents/skills/ and
  inlines their content at session start. That would get the instructions into my context,
  though again without true skill integration (no /slash-command, no auto-triggering from
  the description field).

  Given the options, I think the most practical path for you is the simplest one from that
  thread: just put an @ import line in your CLAUDE.md for each skill file. It's one line per
   skill, no plugins, no hooks, and it survives updates. The downside is you have to
  maintain the list manually if you add new skills.

  Would you like me to add those @ imports to your CLAUDE.md?