File Structure

Overview

The OpenSkills file structure is divided into three categories: skill installation directories, skill directory structure, and AGENTS.md sync files. Understanding these structures helps you better manage and use skills.

Skill Installation Directories

OpenSkills supports 4 skill installation locations, listed in order of priority from high to low:

Priority	Location	Description	When to Use
1	./.agent/skills/	Project-local Universal mode	Multi-agent environments, avoid conflicts with Claude Code
2	~/.agent/skills/	Global Universal mode	Multi-agent environments + global installation
3	./.claude/skills/	Project-local (default)	Standard installation, project-specific skills
4	~/.claude/skills/	Global installation	Skills shared across all projects

Recommendations:

• Single agent environment: Use default .claude/skills/
• Multi-agent environment: Use .agent/skills/ (with --universal flag)
• Cross-project general skills: Use global installation (with --global flag)

Skill Directory Structure

Each skill is a standalone directory containing required files and optional resources:

skill-name/
├── SKILL.md              # Required: Main skill file
├── .openskills.json      # Required: Installation metadata (auto-generated)
├── references/           # Optional: Reference documentation
│   └── api-docs.md
├── scripts/             # Optional: Executable scripts
│   └── helper.py
└── assets/              # Optional: Templates and output files
    └── template.json

File Descriptions

SKILL.md (Required)

Main skill file containing YAML frontmatter and skill instructions:

---
name: my-skill
description: Skill description
---

## Skill Title

Skill instruction content...

Key points:

• Filename must be SKILL.md (uppercase)
• YAML frontmatter must include name and description
• Content uses imperative form

.openskills.json (Required, Auto-generated)

Metadata file automatically created by OpenSkills, recording installation source:

{
  "source": "anthropics/skills",
  "sourceType": "github",
  "repoUrl": "https://github.com/anthropics/skills.git",
  "subpath": "pdf",
  "installedAt": "2026-01-24T12:00:00.000Z"
}

Purpose:

• Supports skill updates (openskills update)
• Records installation timestamp
• Tracks skill source

Source locations:

• src/utils/skill-metadata.ts:29-36 - Write metadata
• src/utils/skill-metadata.ts:17-27 - Read metadata

references/ (Optional)

Stores reference documentation and API specifications:

references/
├── skill-format.md      # Skill format specification
├── api-docs.md         # API documentation
└── best-practices.md   # Best practices

Use cases:

• Detailed technical documentation (keep SKILL.md concise)
• API reference manuals
• Example code and templates

scripts/ (Optional)

Stores executable scripts:

scripts/
├── extract_text.py      # Python script
├── deploy.sh          # Shell script
└── build.js          # Node.js script

Use cases:

• Automation scripts that need to run during skill execution
• Data processing and transformation tools
• Deployment and build scripts

assets/ (Optional)

Stores templates and output files:

assets/
├── template.json      # JSON template
├── config.yaml       # Configuration file
└── output.md        # Sample output

Use cases:

• Templates for content generation by skills
• Configuration file samples
• Expected output examples

AGENTS.md Structure

The AGENTS.md file generated by openskills sync contains the skill system description and available skills list:

Complete Format

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.

How to use skills:
- Invoke: `npx openskills read <skill-name>` (run in your shell)
- The skill content will load with detailed instructions
- Base directory provided in output for resolving bundled resources

Usage notes:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already loaded in your context
</usage>

<available_skills>

<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit for extracting text and tables...</description>
<location>project</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

Component Descriptions

Component	Description
<skills_system>	XML tag marking the skill system section
<usage>	Skill usage instructions (tells AI how to invoke skills)
<available_skills>	List of available skills (one <skill> tag per skill)
<skill>	Single skill information (name, description, location)
<!-- SKILLS_TABLE_START -->	Start marker (for positioning during sync)
<!-- SKILLS_TABLE_END -->	End marker (for positioning during sync)

location field:

• project - Project-local skills (.claude/skills/ or .agent/skills/)
• global - Global skills (~/.claude/skills/ or ~/.agent/skills/)

Directory Lookup Priority

When searching for skills, OpenSkills traverses directories in the following priority order:

// Source location: src/utils/dirs.ts:18-25
[
  join(process.cwd(), '.agent/skills'),   // 1. Project Universal
  join(homedir(), '.agent/skills'),        // 2. Global Universal
  join(process.cwd(), '.claude/skills'),  // 3. Project Claude
  join(homedir(), '.claude/skills'),       // 4. Global Claude
]

Rules:

• Stop searching immediately after finding the first matching skill
• Project-local skills take priority over global skills
• Universal mode takes priority over standard mode

Source location: src/utils/skills.ts:30-64 - Implementation of finding all skills

Example: Complete Project Structure

A typical project structure using OpenSkills:

my-project/
├── AGENTS.md                    # Sync-generated skill list
├── .claude/                     # Claude Code configuration
│   └── skills/                  # Skill installation directory
│       ├── pdf/
│       │   ├── SKILL.md
│       │   ├── .openskills.json
│       │   ├── references/
│       │   ├── scripts/
│       │   └── assets/
│       └── git-workflow/
│           ├── SKILL.md
│           └── .openskills.json
├── .agent/                      # Universal mode directory (optional)
│   └── skills/
│       └── my-custom-skill/
│           ├── SKILL.md
│           └── .openskills.json
├── src/                         # Project source code
├── package.json
└── README.md

Best Practices

1. Directory Selection

Scenario	Recommended Directory	Command
Project-specific skills	.claude/skills/	openskills install repo
Multi-agent sharing	.agent/skills/	openskills install repo --universal
Cross-project general skills	~/.claude/skills/	openskills install repo --global

2. Skill Organization

• Single-skill repository: Place SKILL.md in the root directory
• Multi-skill repository: Each subdirectory contains its own SKILL.md
• Symbolic links: Use symlinks to link to local repositories during development (see Symbolic Link Support)

3. AGENTS.md Version Control

• Recommended to commit: Add AGENTS.md to version control
• CI sync: Run openskills sync -y in CI/CD (see CI/CD Integration)
• Team collaboration: Team members run openskills sync to stay consistent

Lesson Summary

OpenSkills file structure design is concise and clear:

• 4 installation directories: Support project-local, global, and Universal modes
• Skill directories: Required SKILL.md + auto-generated .openskills.json + optional resources/scripts/assets
• AGENTS.md: Sync-generated skill list following Claude Code format

Understanding these structures helps you manage and use skills more efficiently.

Up Next

In the next lesson, we'll learn Glossary.

You will learn:

• Key terminology for OpenSkills and AI skill systems
• Accurate definitions of professional concepts
• Meanings of common abbreviations

---

Appendix: Source Code Reference

Click to expand source code locations

Updated: 2026-01-24

Feature	File Path	Line Numbers
Directory path utilities	src/utils/dirs.ts	1-25
Skill lookup	src/utils/skills.ts	30-84
Metadata management	src/utils/skill-metadata.ts	1-36

Key functions:

• getSkillsDir(projectLocal, universal) - Get skill directory path
• getSearchDirs() - Get 4 search directories (by priority)
• findAllSkills() - Find all installed skills
• findSkill(skillName) - Find specified skill
• readSkillMetadata(skillDir) - Read skill metadata
• writeSkillMetadata(skillDir, metadata) - Write skill metadata