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

> Understand the difference between skills/ and .claude/skills/ directories in AI agents. Learn how to manage generic and Claude-specific skills for host-agnostic architecture. Discover AI skill management.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-09-04

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/start-learning/SKILL.md) and [`skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.claude/skills/start-learning/SKILL.md) and [`.claude/skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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:

```python
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:

```python
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn/SKILL.md) and [`.claude/skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.claude/skills/start-learning/SKILL.md) and [`skills/start-learning/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.