Difference Between skills/ and .claude/skills/ Directories: Host-Agnostic AI Skill Architecture

The skills/ directory serves as the canonical skill library for generic AI agents, while .claude/skills/ functions as a Claude-specific mirror that supports slash-command invocation (e.g., /learn), with both directories containing identical YAML skill definitions to ensure a single source of truth across different host environments.

The rohitg00/ai-engineering-from-scratch repository implements a declarative skill system where interactive teaching routines are defined as self-contained YAML-style files. Understanding the architectural distinction between these two parallel directory structures is essential for developers extending the curriculum or integrating it with diverse AI agent hosts such as Codex, Claude Code, or other open-source tooling.

What Is the skills/ Directory?

The skills/ directory acts as the canonical skill library accessible to all generic agents. This visible directory contains the primary source files that hosts load when invoking skills by plain name (e.g., learn, start-learning).

According to the repository source code, this directory houses declarative skill definitions such as skills/start-learning/SKILL.md and skills/learn/SKILL.md. These files define interactive teaching routines using YAML-frontmatter metadata and markdown content, enabling any compatible host to parse and execute the curriculum without host-specific modifications.

What Is the .claude/skills/ Directory?

The .claude/skills/ directory serves as a Claude-specific mirror of the canonical library. The hidden .claude prefix signals to the Claude Code runtime that these files should be used when the host expects slash-prefixed commands (e.g., /learn rather than learn).

This directory contains identical copies of the skill definitions found in the root skills/ folder, such as .claude/skills/start-learning/SKILL.md and .claude/skills/learn/SKILL.md. The content remains byte-for-byte identical to the canonical versions, ensuring behavioral consistency while accommodating Claude's command syntax requirements.

Why Maintain Parallel Directory Structures?

The duplication is intentional and serves a specific architectural purpose: host-agnostic curriculum delivery. By maintaining separate directories rather than conditional logic within the skill files themselves, the repository achieves several critical objectives:

• Single Source of Truth: Each skill definition remains unmodified and self-contained, reducing the risk of host-specific drift or version mismatches.
• Clean Host Integration: Generic agents read from skills/, while Claude-focused agents automatically resolve to .claude/skills/ without requiring runtime configuration or file-path manipulation.
• Namespace Isolation: The hidden .claude directory keeps Claude-specific organizational metadata separate from the generic skill library, preventing namespace pollution in the root directory.

This pattern allows the curriculum to function seamlessly across Codex-style environments, Claude Code, and other emerging agent hosts without modifying the underlying skill definitions.

Loading Skills from Each Directory

When implementing a skill loader for generic hosts, you target the canonical directory:

import yaml
import pathlib

def load_skill(name: str):
    """Load a skill definition for generic agents (Codex-style)."""
    path = pathlib.Path("skills") / name / "SKILL.md"
    with path.open() as f:
        return yaml.safe_load(f)

skill = load_skill("learn")
print(skill["name"])      # → learn

For Claude-compatible hosts that require slash-command support, load from the mirrored location:

def load_claude_skill(name: str):
    """Load a skill definition for Claude-specific hosts."""
    path = pathlib.Path(".claude/skills") / name / "SKILL.md"
    with path.open() as f:
        return yaml.safe_load(f)

claude_skill = load_claude_skill("learn")
print(claude_skill["name"])   # → learn (identical content)

Both functions return identical YAML structures, confirming that the .claude/skills/ directory contains perfect mirrors of the canonical definitions.

Summary

• The skills/ directory contains the canonical skill library used by generic AI agents and open-source tooling when invoking skills by plain name.
• The .claude/skills/ directory provides a hidden mirror for Claude Code compatibility, enabling slash-command invocation (e.g., /learn) without altering skill content.
• Files such as skills/learn/SKILL.md and .claude/skills/learn/SKILL.md contain identical YAML definitions, maintaining a single source of truth.
• This parallel structure eliminates conditional logic in skill implementations and ensures host-agnostic curriculum delivery across Codex, Claude, and other agent runtimes.

Frequently Asked Questions

Are the skill files in .claude/skills/ different from those in skills/?

No. The content is byte-for-byte identical. Files such as .claude/skills/start-learning/SKILL.md and skills/start-learning/SKILL.md contain the same YAML-frontmatter definitions and markdown content. The duplication exists solely to support different invocation patterns (slash-commands vs. plain names) across host environments.

Why use a hidden directory for Claude-specific skills?

The .claude/ naming convention follows Unix hidden-file standards (prefixing with a dot) to logically separate Claude-specific organizational metadata from the generic curriculum structure. This prevents the Claude-specific mirror from cluttering the root directory listing while still remaining accessible to the Claude Code runtime, which specifically checks for this directory pattern.

Can I use the skills/ directory with Claude Code?

While Claude Code can technically read files from any directory, the .claude/skills/ directory is specifically designed for Claude's slash-command interface. If you invoke skills using the plain name (e.g., learn), the generic skills/ directory would suffice. However, for native Claude integration using /learn syntax, the runtime expects to resolve definitions from .claude/skills/.

How do I add a new skill to both directories?

Create your skill definition (typically a SKILL.md file with YAML frontmatter) and place an identical copy in both skills/<skill-name>/SKILL.md and .claude/skills/<skill-name>/SKILL.md. Ensure the directory structure, filename, and content match exactly between both locations to maintain consistency across host environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}