[Blog] New post on organization coding agent skills

[leecalcote]

A new blog post fitting the following description is requested to be written by a community member:

Topic: in what directory should coding agent skills be placed in open source repos?

Core points to convey in the post:

Here is a draft of the post that needs to be rewritten:

The placement of agent skills in an open-source repository depends on whether you are adding skills to help an AI agent work on your specific project, or if you are publishing a standalone skill for others to download.

First, a quick point of clarification: Under the open Agent Skills specification (adopted by Claude, Cursor, GitHub Copilot, and others), the file is strictly named SKILL.md (all caps), and it must live inside its own named folder rather than existing as a standalone file.

Here is exactly where you should place them based on your goal:

1. Adding Skills to Help Agents Work on Your Project

If you are adding skills to teach coding agents how to navigate, build, or deploy your specific codebase, they should be placed in a hidden directory at the root of your project.

The emerging universal standard is the .agents/ directory, but major tools also check their own specific folders.

• The Open Standard: .agents/skills/<skill-name>/
• VS Code / GitHub Copilot: .github/skills/<skill-name>/
• Cursor: .cursor/skills/<skill-name>/
• Claude Code: .claude/skills/<skill-name>/

Recommended Approach: Put your skills in .agents/skills/ as most modern agents (including Cursor and Codex) will automatically discover them there.

2. Publishing a Skill for the Community

If your open-source repository exists solely to distribute a reusable skill (for example, to be installed via Vercel's npx skills CLI or Vercel's skills.sh directory), the placement changes:

• Single-Skill Repository: Place the SKILL.md file directly at the root of the repository.
• Multi-Skill Monorepo: If your repository contains a collection of skills (like the official anthropics/skills or huggingface/skills repos), group them in a visible skills/ folder at the root (e.g., skills/my-custom-skill/SKILL.md).

---

The Standard Directory Structure

Regardless of where the root folder lives, every skill must follow a progressive disclosure pattern. The SKILL.md file contains the YAML frontmatter (metadata) and core instructions, while heavier files are kept in subdirectories so they don't bloat the agent's context window until explicitly needed.

Here is what a complete, standard skill directory looks like:

.agents/
└── skills/
    └── deploy-app/                 # The name of your skill
        ├── SKILL.md                # REQUIRED: Frontmatter + core instructions
        ├── scripts/                # OPTIONAL: Executable code (e.g., Python/Bash scripts)
        ├── references/             # OPTIONAL: Dense docs or API schemas loaded on demand
        └── assets/                 # OPTIONAL: JSON templates, static files, etc.

---

Contributor Resources

The layer5.io website uses Gatsby, React, and GitHub Pages. Site content is found under the master branch.

• See contributing instructions
• See Layer5 site designs in this Figma project.