Agents Best Practices

Agent Skills Best Practices 🤖

Vendor-neutral best practices for the `.agents/skills/` ecosystem — governance and discovery tools for AI agent skills.

What is `.agents/skills/`? 📂

A directory convention where AI agent skills live as self-contained packages.

.agents/skills/my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
└── references/       # Optional: supplementary docs (opt-in, not default)

Supported by **Claude Code**, **OpenAI Codex**, **Gemini CLI**, **VS Code Copilot**, **Cursor**, and **JetBrains**.

Skills in This Repo 🛠️

This repo ships **governance** tooling + **discovery** tooling:

Skill	Purpose
🧲 skill-finder	Finds 1184+ existing official skills from 40+ teams before creating new ones
✨ skill-creator	Creates new skills through a draft-test-iterate loop
🔍 improving-skills	Audits skills, AGENTS.md, and CLAUDE.md against the agentskills.io spec

**Workflow**: `skill-finder` (check first) → `skill-creator` (if nothing fits) → `improving-skills` (audit the result)

Installing Skills 📥

Drop a skill directory at one of these paths. Agents discover it automatically.

Scope	Path	Platforms
Repo (team-wide, committed)	.agents/skills//	Claude Code, Codex, Gemini CLI
User (global, vendor-neutral)	~/.agents/skills//	All agentskills.io-compatible tools
User (per-platform)	~/.claude/skills/, ~/.gemini/skills/	Platform-specific alternatives

Try this repo's skills 🚀

git clone https://github.com/laguagu/agents-best-practices.git
cp -r agents-best-practices/.agents/skills/skill-finder ~/.agents/skills/
cp -r agents-best-practices/.agents/skills/skill-creator ~/.agents/skills/
cp -r agents-best-practices/.agents/skills/impr