>_

Writing Effective Descriptions

Your skill's description is crucial for discoverability and user understanding.

The Two Descriptions

1. Frontmatter Description (200 chars)

Appears in:

  • Search results
  • Skill cards
  • Index listings

Goal: Quickly communicate value and scope.

2. Content Description (unlimited)

Appears in:

  • Skill detail page
  • Documentation

Goal: Provide comprehensive understanding.

Frontmatter Description Tips

Lead with Value

Start with what the user gains, not what the skill is.

Good:

"Write cleaner React code with component patterns, performance tips, and accessibility guidelines."

Bad:

"This skill contains guidelines for React development."

Include Keywords

Help users find your skill through search.

Good:

"TypeScript type safety guidelines: generics, type guards, utility types, and strict mode best practices."

Bad:

"Guidelines for type-safe code."

Be Specific About Scope

Set clear expectations.

Good:

"API security checklist: authentication, authorization, input validation, and rate limiting for REST APIs."

Bad:

"Security best practices."

Use Active Language

Make it action-oriented.

Good:

"Build accessible React components with ARIA labels, keyboard navigation, and screen reader support."

Bad:

"Accessibility information for React."

Templates

For Guidelines Skills

[Action] [domain] with [key feature 1], [key feature 2], and [key feature 3].

Example:

"Write maintainable CSS with BEM naming, utility classes, and responsive design patterns."

For Review Skills

[Review type] for [audience]: [check 1], [check 2], and [check 3].

Example:

"Code review guidelines for teams: security checks, performance analysis, and style consistency."

For Integration Skills

[Integrate/Connect] [technology] with [approach]: [feature 1] and [feature 2].

Example:

"Integrate Stripe payments with best practices: webhook handling and error recovery."

Common Mistakes

Too Vague

Problem: "Guidelines for better code." Better: "Python code quality: PEP 8 style, type hints, and documentation standards."

Too Long

Problem: 300+ character descriptions that get truncated. Better: Keep under 180 characters. Use the content section for details.

Jargon Without Context

Problem: "SOLID principles for DDD with CQRS patterns." Better: "Clean architecture patterns: single responsibility, dependency injection, and domain modeling."

No Differentiator

Problem: "React development guidelines." Better: "React server components: streaming, suspense, and data fetching patterns."

Keyword Strategy

Include terms users might search for:

| Category | Keywords | |----------|----------| | Technology | React, TypeScript, Python, AWS | | Domain | authentication, payments, analytics | | Task | review, testing, deployment | | Quality | security, performance, accessibility |

Testing Your Description

  1. Search test: Would you find this searching for related terms?
  2. Scan test: Can you understand the skill in 5 seconds?
  3. Differentiation test: How is this different from similar skills?
  4. Action test: Is it clear what you'll do with this skill?

Next Steps

Edit this page on GitHub