skills.md

Proposal: Standardizing the Location of skill.md

Background / Current Situation

At present, different programming tools store skill.md in different locations, usually tightly coupled to their own tool-specific directories. For example:
• Claude Code places skill.md under the .claude/ directory
• Other tools may maintain their own copies of skill.md in private or hidden directories

This approach—where each tool maintains its own version of skill.md—has started to show several drawbacks in practice.

Problems
• High maintenance cost
The same skill definitions need to be updated in multiple places.
• Inconsistency risk
Over time, different copies of skill.md can diverge and become out of sync.
• Strong tool coupling
Storing skills in tool-specific directories makes cross-tool reuse harder and increases migration costs.

Proposal

We propose decoupling skill.md from individual tools and adopting a tool-agnostic, standardized location:

.skills/
  skill-name/
    SKILL.md

In other words:

skill.md should be placed under the .skills directory at the project root, rather than inside tool-specific directories such as .claude/.

Design Principles
• Tool-agnostic
Skill definitions should not depend on any specific tool.
• Single Source of Truth
Avoid maintaining multiple copies of the same skill definitions.
• Extensibility
The .skills directory can be extended in the future to hold additional skill-related metadata.

Migration and Compatibility
• Existing tools (including Claude Code) can remain compatible by reading from .skills/skill.md.
• During a transition period, tool-specific skill.md files may continue to exist, but creating new ones is discouraged.
• The long-term goal is for .skills/skill.md to become the default and recommended standard location.

Conclusion

Moving skill.md out of tool-specific directories (such as .claude/) and into a shared .skills directory reduces duplication, improves consistency, and lays a stronger foundation for multi-tool interoperability and automation.

⸻

If you want a more formal RFC tone, a shorter issue-style version, or wording tailored specifically for Claude Code maintainers, I can refine it further.