diff --git a/README.md b/README.md index 1766599..00dc4b7 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ The most contributed Agent Skills repository, built and maintained together with - [Skills by WordPress Development Team](#skills-by-wordpress-development-team) - [Skills by Transloadit Team](#skills-by-transloadit-team) - [Community Skills](#community-skills) +- [Skill Quality Standards](#skill-quality-standards) ### Skills Paths for Other AI Coding Assistants @@ -646,6 +647,25 @@ Domain-specific knowledge for Azure SDK and Foundry development. +## Skill Quality Standards + +As the ecosystem grows, consistent quality helps agents discover and use skills reliably. The following references and criteria keep the bar high. + +### Canonical References + +- **[AgentSkills.io Spec](https://agentskills.io)** -- The open standard for skill metadata, structure, and interoperability across tools. +- **[Anthropic Best Practices](https://platform.claude.com)** -- Official guidance on writing effective skills for Claude Code. +- **[anthropics/skills](https://github.com/anthropics/skills)** -- Anthropic's official skills repository, useful as a reference implementation. + +### Quality Criteria + +| Area | Guideline | +|------|-----------| +| **Description** | Write in third person. State *what* the skill does and *when* to use it. Use specific keywords agents can match on (e.g., "PostgreSQL migration" not "database stuff"). | +| **Progressive disclosure** | Keep top-level metadata under ~100 tokens. Skill body should stay below 500 lines. Load resources (large docs, schemas) on demand, not inline. | +| **No absolute paths** | Never hard-code machine-specific paths like `/Users/alice/`. Use relative paths or well-known variables (`$HOME`, `$PROJECT_ROOT`). | +| **Scoped tools** | Request only the tools the skill actually needs. Avoid blanket `"tools": ["*"]`. Declare tool dependencies explicitly. | + ## 🤝 Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.