Skip to content

Proposal: include a standard folder where agent skills should be #15

Open

Description

@douglascamata

I highly appreciate that skills is becoming a standard that we can use across many different agent harnesses.

To make it even smoother, I believe that agreeing on a standard name for the agent skills folder would benefit everyone. This would allow different harnesses to have a default folder to find skills without requiring each project to put them in a different folder and create symlinks that match the specific folder of each harness.

Example: Claude is looking at .claude/skills/ and Github Copilot is looking at .github/skills/.

Edit: now we have Codex also looking at its own folder .codex/skills/

My suggestion for the name would be .agents/skills/, but I don't really care much about the name as long as it's agreed upon and standardized. It could even be just .skills/.

Adoption

Please help to keep the lists below up to date. 😄

Ready

Pending

Not adopting yet

There are too many tools to list here. Anyone not mention in "ready" or "pending" is considered not adopting yet.

Activity

  1. edu-ap commented on Dec 19, 2025

    @edu-ap

    Love the idea of converging on a standard skills folder so we can avoid every harness inventing its own layout.

    One tweak I’d suggest is using .llm/skills/ (or .llm/) rather than .agent/skills/.
    Other ecosystems tend to name these shared hidden directories after the core runtime/capability, e.g. Python tools agree on .venv for virtual environments, VS Code uses .vscode/ for project‑local editor and extension settings, and .NET uses .dotnet/ (plus .config) for CLI tools and manifests.

    In the LLM world, the common denominator across frameworks is the LLM itself, while “agent” is an architectural pattern that differs a lot (and sometimes isn’t used at all). A neutral .llm/ namespace would work for:

    • agent skills (.llm/skills/),
    • model/provider config (.llm/config/), and
    • other shared metadata,
      and would still make sense in projects that use LLMs directly without an “agent” concept.

    Concretely: if tools like Claude, Copilot, and others agree to look in .llm/skills/ by default (while maybe still supporting their legacy .claude/skills/, .github/skills/, etc.), we’d get a cross‑tool convention that matches how other ecosystems have handled this problem.

  2. changed the title [-]Proposal: include a standard folder where agent skill will be[/-] [+]Proposal: include a standard folder where agent skills should be[/+] on Dec 19, 2025
  3. Aranmobinarann commented on Dec 19, 2025

    @Aranmobinarann

    Don't be really tired.

  4. numman-ali commented on Dec 19, 2025

    @numman-ali

    it should be .agents, it aligns with AGENTS .md - and distribution is better than semantics

    Without adoption we don't have much movement

  5. douglascamata commented on Dec 19, 2025

    @douglascamata
    Author

    To have adoption, there must be an agreement, like eventually everyone agreed on AGENTS.md but at first used separate files.

    BTW, Codex just launched skills support on .codex/skills. 🤣

    So three symlinks already. Now we only miss Google out of the big providers.

  6. jameskanyiri commented on Dec 20, 2025

    @jameskanyiri

    I agree that we should converge on a single standard, and I’d advocate for using .agent/skills/

    These skills are specifically meant for agents, not just generic LLM usage, so tying the convention to the agent construct feels clearer and more intentional. Similar to how AGENTS.md became a focal convention, a dedicated agent/ namespace keeps the ecosystem conceptually aligned, avoids over-generalizing into the broader “LLM” space, and helps reinforce that this directory represents agent-oriented capabilities rather than model configuration or runtime metadata.

  7. TabishB commented on Dec 20, 2025

    @TabishB

    +1 This is a super important aspect of the standard. The last thing we need is every coding agent provider having a different directory location that we need to either copy over or create symlinks for.

    Setting a standard on a common directory name is crucial.

  8. skillcreatorai commented on Dec 20, 2025

    @skillcreatorai
    Contributor

    While the path standardization debate continues, there's a practical alternative: tooling that abstracts the paths.

    For example, ai-agent-skills lets you install with one command:

    npx ai-agent-skills install pdf --agent claude   # → ~/.claude/skills/
    npx ai-agent-skills install pdf --agent cursor   # → .cursor/skills/
    npx ai-agent-skills install pdf --agent goose    # → ~/.config/goose/skills/

    Users don't need to know where skills go. The CLI handles the mapping internally.

    This doesn't require any agent to change their paths - just a layer that knows the current mapping. Not saying this replaces standardization, but it solves the user pain point today while the discussion continues.

  9. airtonix commented on Dec 30, 2025

    @airtonix

    or just use symlinks.

    I use comtrya to manage my dotfiles and i just have all this symlinked to the different directories.

    this thread just feels like a huge bike shed tbh.

  10. Dyrits commented on Dec 31, 2025

    @Dyrits

    That's a big issue. There should be a standard to provide context to the agents.

    The ecosystem has standardized the technical layers (tools, communication) but not the semantic layers (instructions, context). That's a problem.

  11. airtonix commented on Jan 2, 2026

    @airtonix

    So what happens when people need to source skills from more than one place?

  12. xxchan commented on Jan 4, 2026

    @xxchan

    I think the key here is lifecycle: agent skills are meant to be created and iterated constantly (often by the agent itself). Without a shared, standard folder, this becomes fragmented across harnesses and quickly turns into sync chaos. A canonical repo path (name doesn’t matter much) would make skills a first-class, continuously evolving asset rather than per-harness copies.

    Codex doesn't event support symlinks btw

  13. verdie-g commented on Jan 7, 2026

    @verdie-g

    @ericharmeling @klazuka could you share what are you thoughts about this? 🙏

  14. mderazon commented on Jan 8, 2026

    @mderazon

    I agree, this is frustrating. It creates a vendor lock-in for specific agent that is more of a nuisance than lock-in because it can be hacked to be circumvented by symlinks / copying the skills folder across .gemini / .claude / .github folders.

    Same for agent instructions, this whole thing is a mess

  15. mderazon commented on Jan 8, 2026

    @mderazon

    While the path standardization debate continues, there's a practical alternative: tooling that abstracts the paths.

    For example, ai-agent-skills lets you install with one command:

    npx ai-agent-skills install pdf --agent claude # → ~/.claude/skills/
    npx ai-agent-skills install pdf --agent cursor # → .cursor/skills/
    npx ai-agent-skills install pdf --agent goose # → ~/.config/goose/skills/
    Users don't need to know where skills go. The CLI handles the mapping internally.

    This doesn't require any agent to change their paths - just a layer that knows the current mapping. Not saying this replaces standardization, but it solves the user pain point today while the discussion continues.

    This copies (duplicates) the skills across folders, to me that's horrible

  16. 124 remaining items

  17. Aesthermortis commented on Jun 17, 2026

    @Aesthermortis

    Codex reads universal paths, and you can also set a path outside of the supported ones, and through load map in agents.md the AI ​​loads the content indicated in the path you have set.

  18. lancy69 commented on Aug 13, 2026

    @lancy69

    People have mentioned using $XDG_CONFIG_HOME/agents/skills. But it might be better to use $XDG_DATA_HOME/agents/skills IMHO, for some skills contain large, less edit-friendly resources.

  19. tmccombs commented on Aug 15, 2026

    @tmccombs

    Or both?

  20. lancy69 commented on Aug 20, 2026

    @lancy69

    Or both?

    Both would also be great! 👍 This way the existing workflows will not break while those who prefer XDG can get what they want.

  21. karlhorky commented on Aug 26, 2026

    @karlhorky

    @douglascamata would you also be open to keeping your original issue description updated to track documentation / implementation PRs in the popular skills CLI?

    For example, I noticed just today that the skills CLI implementation and documentation is outdated for Codex (~/.codex/skills/ instead of ~/.agents/skills/):

    Image

    So that would mean that if you used npx skills ... commands, they are currently installed in the ~/.codex/skills/ folder for Codex.

    Only a few "universal agents" have been implemented and documented so far (Cline, Dexto, Kimi Code CLI, Loaf, Warp, Zed):

    Image

    I did a PR just now for updating the implementation and documentation for using ~/.agents/skills/ for Codex:

    Another similar older (merged) PR for Cline:

  22. Aesthermortis commented on Aug 26, 2026

    @Aesthermortis

    I cancelled Claude's PRO account because it's terrible. It doesn't read the instructions in the specified paths, and everything is opaque; you can't tell if it's doing anything or not. Codex, on the other hand, displays the commands, reads the files in any path you specify, and follows the rules precisely. It also shows you exactly when each skill is used.

  23. yordis commented on Aug 27, 2026

    @yordis

    @Aesthermortis I think that is an skills issue, good to know. Thanks for sharing here, very insightful!

  24. douglascamata commented on Aug 28, 2026

    @douglascamata
    Author

    @karlhorky unfortunately I can't keep up with updating this issue anymore and tracking here behavior of an external tool, in this case owned by Vercel and not affiliated in any way with this organization, doesn't make sense, imho.

  25. Dakta commented on Sep 8, 2026

    @Dakta

    Previous discussion in the AGENTS.md repo got sidetracked badly by debating Claude's Rules feature. Other past efforts at standardizing this have all succumbed to similar scope-creep. Therefore I propose some guidelines to begin an open standard for consolidated project configuration in .agents/ without being bogged down inventing other standards: agentsmd/agents.md#71 (comment)

    Let's pick the existing standards: AGENTS.md, Agent Skills, and the de-facto mcp.json standard, and use them as the basis:

    .agents/
    ├─ AGENTS.md # allow moving this out of the project root
    ├─ mcp.json # vendors adopt loading `mcpServers` JSON dict from this file
    ├─ skills/
    │  ├─ my-skill/ # standard Agent Skills directory
    │     ├─ SKILL.md
    

    As new standards arise for things like Rules, Tasks, Personas, Memory, or (in my view the most pressing) Sub-Agents, their configurations can be incorporated by reference. But we don't need to wait for any of those things to get started.

  26. Pjrich1313 commented on Sep 8, 2026

    @Pjrich1313

    Add to build

  27. Aesthermortis commented on Sep 9, 2026

    @Aesthermortis

    The solution would be to isolate Claude while everyone follows fairer and less selfish standards.

  28. Pjrich1313 commented on Sep 9, 2026

    @Pjrich1313

    I use both Claude and Grok

  29. Pjrich1313 commented on Sep 10, 2026

    @Pjrich1313
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions