skill-granularity-convention

Skill granularity should follow the single-purpose principle: each skill covers one clear objective. Split a skill when it has multiple distinct objectives, complex workflows across unrelated domains, or excessive categories. For example, a skill covering architecture, database design, and API design should split into three focused skills, each with 3–5 responsibilities and 2–5 workflow steps.

A well-scoped skill has a single-line description (about 50 characters), 3–5 clear responsibilities, and 2–5 workflow steps or categories. This structure ensures maintainability and reusability. Skills with overly broad descriptions, more than 5 responsibilities, or unclear purpose violate granularity conventions and should be redesigned.

Merge skills when they are overly small with minimal responsibility, share strong inter-dependencies requiring frequent coordination, or contain high duplication in logic and workflows. Merging reduces maintenance overhead and improves reusability, but only if the combined skill maintains a single, coherent purpose.

Granularity principles govern skill design decisions, evaluation criteria, and governance policies. They standardize how to assess skill responsibility scope, categorization, splitting and merging decisions, and reuse patterns. This ensures consistency across skill portfolios and enables maintainable, composable AI components.

Splitting by workflow phases separates skills across different stages of execution (e.g., planning, implementation, validation). Splitting by categorical complexity breaks apart skills where each category represents a distinct domain (e.g., database design vs. API design). Both signal a violation of single-purpose principle and warrant separate skills.

Yes. Single-purpose design maximizes reusability: a focused skill with clear responsibility and minimal scope is easier to integrate into different workflows. However, maintain modularity through proper granularity—avoid combining unrelated responsibilities that limit where the skill can be applied.