Skill Style Guide for a Shared Engineering Library

Background

A mid-sized software company has been embracing agentic development across its 60-engineer organisation. Over the past year, individual teams have built their own skills in isolation, leading to duplicated effort, inconsistent naming, and a growing list of abandoned skills that nobody trusts.

The platform engineering team has been asked to fix this by launching a canonical shared skill library — a single, curated repository that all product teams contribute to and pull from. Before opening the repository, the team needs a skill style guide: a document that sets standards for structure, metadata, documentation, versioning, and quality that all contributors must follow.

The style guide will be the authoritative reference for contributors submitting skills via pull request, reviewers approving changes, and consumers deciding which skill to use. Getting these standards right from the start is important: retrofitting conventions onto 80+ existing skills later will be expensive.

Output Specification

Write a skill style guide document saved as skill-style-guide.md. The guide should cover at minimum:

• Required metadata fields (name, description, version, author)
• File structure and naming conventions
• Documentation requirements (what must be explained in a skill's header)
• Versioning conventions (how to signal breaking vs. non-breaking changes)
• Quality requirements (what makes a skill ready to merge)
• Security requirements (what must be avoided in any submitted skill)
• Lifecycle and maintenance expectations (what happens to skills that go stale)

The guide should be practical and ready for real contributors to follow.