Designing Skills with Clear Purpose

The most common skill design mistake is being too broad. A skill that tries to cover "all of Python" ends up mediocre at everything. A skill focused on "Python async patterns" can be exceptional at that one thing.

Clear purpose is the foundation of effective skills. It determines what the skill covers, how it provides value, and when it should be used. This guide teaches you to scope skills properly, define clear purposes, and avoid the traps of unfocused design.

Why Purpose Matters

The Focus Principle

Consider two skill descriptions:

Unfocused:

# Code Quality

Help with code quality across any language or domain.

Focused:

# Python Type Checking

Evaluate and improve type annotations in Python code,
focusing on mypy compatibility, generic usage, and
type guard patterns.

The focused skill will outperform the unfocused one every time for Python type checking. It knows exactly what to check, what patterns to suggest, and what issues to flag.

Cognitive Load

LLMs work within context limits. A broad skill that includes everything:

Consumes more context tokens
Creates decision fatigue (which guidance applies?)
Produces generic rather than specific advice

A focused skill:

Uses context efficiently
Provides clear, applicable guidance
Delivers specific, actionable recommendations

Composability

Focused skills compose better. You can load:

Python type checking skill
Python async patterns skill
Code review skill

Each contributes specific expertise without conflict. A single "Python everything" skill cannot combine with others as cleanly.

Defining Clear Purpose

The Single Responsibility Test

A skill should have one primary responsibility. Test with this question:

"What does this skill do?"

Good answers:

"Reviews Python code for type safety issues"
"Generates API documentation in OpenAPI format"
"Evaluates React components for accessibility"

Bad answers:

"Helps with code" (too vague)
"Reviews code and writes documentation and generates tests" (too many things)
"Handles Python and JavaScript and TypeScript" (too many domains)

If you cannot answer in one sentence, the skill is too broad.

Purpose Statement Format

Write an explicit purpose statement:

# [Skill Name]

## Purpose

This skill [action verb] [specific domain] by [method/approach].

**Primary focus:** [One thing]
**Secondary focus:** [Optional, closely related thing]
**Not covered:** [Explicit exclusions]

Example:

# React Performance

## Purpose

This skill evaluates React applications for performance issues
by analyzing component structure, render patterns, and state management.

**Primary focus:** Identifying unnecessary re-renders and optimization opportunities
**Secondary focus:** Suggesting performance-aware patterns
**Not covered:** General React patterns (see react-patterns skill), testing, accessibility

Scope Boundaries

Explicit boundaries prevent scope creep:

## Scope

### In Scope
- Component render optimization
- State management efficiency
- Memoization strategies
- Bundle size impact
- Virtual DOM considerations

### Out of Scope
- Business logic review
- API design
- Styling/CSS
- Testing strategies
- Accessibility (see react-accessibility skill)

### Boundary Cases
- State management patterns: In scope only for performance implications
- Data fetching: In scope for caching/revalidation, not for API design

Purpose Discovery

From Pain Points

What problems do you solve repeatedly?

Pain point: "I keep reviewing code and missing the same type issues"
Purpose: Type safety review skill

Pain point: "Documentation is inconsistent across teams"
Purpose: Documentation format skill

Pain point: "New hires make the same security mistakes"
Purpose: Security review skill for common vulnerabilities

From Expertise

What do you know that others need to learn?

Expertise: "I understand async Python deeply"
Purpose: Python async patterns skill

Expertise: "I know our API standards thoroughly"
Purpose: Company API standards skill

Expertise: "I spot performance issues quickly"
Purpose: Performance code review skill

From Repetition

What instructions do you type repeatedly?

Repetition: "Check for null safety, verify types, look for any usage"
Purpose: TypeScript strictness skill

Repetition: "Ensure error handling, validate input, check edge cases"
Purpose: Defensive coding skill

Repetition: "Use our commit format, include ticket numbers, sign off"
Purpose: Git workflow skill

Skill Scoping Techniques

Start Narrow, Expand Carefully

Begin with the smallest useful scope:

Iteration 1:

# Python Dict Type Hints

Type hints specifically for dictionary types in Python:
- TypedDict usage
- Generic dict patterns
- Dict vs Mapping

After success, consider if expansion is needed:

Iteration 2:

# Python Collection Type Hints

Type hints for Python collections:
- Lists, Sets, Dicts
- Sequence vs Collection vs Iterable
- Generic patterns

Only expand if the broader skill remains focused.

Split When Unclear

If purpose becomes unclear, split:

Before (unfocused):

# API Development

Design APIs, document them, test them, secure them...

After (split):

# API Design Patterns
RESTful design, resource modeling, versioning

# API Documentation
OpenAPI specs, endpoint documentation, examples

# API Security
Authentication, authorization, input validation

# API Testing
Contract testing, integration testing, mocking

Each resulting skill has clear purpose.

Depth Over Breadth

Prefer deep expertise in narrow area:

Shallow and broad:

# Security

- SQL injection
- XSS
- CSRF
- Auth issues
- Encryption
- [20 more topics...]

Deep and narrow:

# SQL Injection Prevention

## Understanding SQL Injection
- What it is
- How it works
- Why it is dangerous

## Detection
- Pattern recognition
- Dynamic SQL red flags
- ORM misuse patterns

## Prevention
- Parameterized queries
- ORM best practices
- Input validation layers

## Verification
- Testing for injection
- Code review checklist
- Automated scanning

## Examples
[Detailed examples for each database and ORM]

The deep skill provides more value for its specific domain.

Purpose Statement Examples

Good Purpose Statements

## Purpose: React Hook Dependencies

Analyze React hooks (useEffect, useMemo, useCallback) for
dependency array issues, including missing dependencies,
stale closures, and unnecessary dependencies.

## Purpose: Git Commit Messages

Guide creation of conventional commit messages that clearly
communicate the type, scope, and nature of changes following
the Conventional Commits specification.

## Purpose: Python Async Code Review

Evaluate Python async/await code for correctness and performance,
focusing on proper coroutine usage, avoiding blocking calls,
and efficient task management with asyncio.

Improved Purpose Statements

Before:

Help with testing.

After:

## Purpose: Pytest Unit Testing

Guide creation of effective pytest unit tests with emphasis on
test isolation, fixtures, parametrization, and meaningful assertions.
Focused on testing Python functions and classes, not integration or e2e.

Before:

Code review stuff.

After:

## Purpose: Security-Focused Code Review

Review code specifically for security vulnerabilities, including
injection flaws, authentication issues, authorization gaps,
and data exposure risks. Follows OWASP Top 10 as primary framework.

Testing Purpose Clarity

The User Test

Imagine a new team member reads your skill. Can they answer:

When should I use this skill?
What will it help me with?
What should I NOT use it for?

If any answer is unclear, refine the purpose.

The Non-Overlap Test

Compare with existing skills:

Does this skill duplicate another?
Is the boundary between skills clear?
Could requests go to either skill ambiguously?

If overlaps exist, clarify boundaries or merge skills.

The Output Test

Given the purpose, are expected outputs clear?

What kind of output will this skill produce?
In what format?
With what level of detail?

If outputs are unpredictable, the purpose may be too vague.

Documenting Purpose

Standard Sections

# [Skill Name]

## Purpose
One paragraph describing what this skill does.

## When to Use
- Situation 1
- Situation 2
- Situation 3

## When NOT to Use
- Situation 1 (use [X] instead)
- Situation 2 (use [Y] instead)

## What This Skill Provides
- Capability 1
- Capability 2

## What This Skill Does NOT Provide
- Out of scope 1
- Out of scope 2

## Related Skills
- [Skill A]: For [related purpose]
- [Skill B]: For [related purpose]

Example Documentation

# TypeScript Strict Mode

## Purpose
Evaluate TypeScript code for strict mode compliance and type safety,
identifying issues that would cause errors with strict flags enabled
and suggesting improvements for type-safe code.

## When to Use
- Migrating JavaScript to TypeScript
- Enabling strict mode on existing codebase
- Reviewing TypeScript PRs for type safety
- Learning TypeScript type system best practices

## When NOT to Use
- JavaScript-only codebases (no TypeScript)
- Questions about TypeScript build/config (see typescript-config skill)
- React-specific TypeScript patterns (see react-typescript skill)
- Node.js-specific TypeScript patterns (see node-typescript skill)

## What This Skill Provides
- Identification of `any` type usage that should be stricter
- Detection of missing null checks
- Suggestions for proper generic usage
- Recommendations for type guards and assertions
- Guidance on strict compiler options

## What This Skill Does NOT Provide
- General TypeScript tutoring
- Build configuration help
- Framework-specific patterns
- Performance optimization

## Related Skills
- react-typescript: TypeScript patterns specific to React
- typescript-config: tsconfig.json and build setup
- code-review: General code review (includes TypeScript)

Common Purpose Mistakes

Mistake: Feature Creep

# Python Review

Review Python code for style, types, performance, security,
testing, documentation, architecture...

Problem: Too many concerns, cannot excel at any.

Fix: Split into focused skills for each concern.

Mistake: Vague Scope

# Better Code

Help make code better.

Problem: No clear domain, audience, or output.

Fix: Define specific language, type of improvement, and context.

Mistake: Hidden Assumptions

# API Review

Review APIs for quality.

Problem: Which kind of API? REST? GraphQL? RPC? Internal? Public?

Fix: Make assumptions explicit: "Review REST APIs intended for public consumption."

Mistake: Missing Boundaries

# JavaScript Expert

Everything about JavaScript.

Problem: No boundaries, overlaps with many other skills.

Fix: Focus: "JavaScript async patterns" or "JavaScript testing with Jest."

Summary

Clear purpose is the foundation of effective skills. A well-defined purpose:

Focuses the skill on one thing done well
Sets expectations for what the skill provides
Defines boundaries to prevent scope creep
Enables composition with other skills
Guides users to appropriate usage

When designing skills:

Start narrow, expand only when proven valuable
Split unclear purposes into focused skills
Choose depth over breadth
Document purpose explicitly with when to use and when not to use
Test clarity with users and against overlaps

The result is skills that consistently deliver exceptional value for their specific domain.

Ready to inject domain context into your skills? Continue to Context Injection: Teaching AI Domain Knowledge for advanced context design.

Designing Skills with Clear Purpose

Why Purpose Matters

The Focus Principle

Consider two skill descriptions:

Unfocused:

# Code Quality

Help with code quality across any language or domain.

Focused:

# Python Type Checking

Evaluate and improve type annotations in Python code,
focusing on mypy compatibility, generic usage, and
type guard patterns.

The focused skill will outperform the unfocused one every time for Python type checking. It knows exactly what to check, what patterns to suggest, and what issues to flag.

Cognitive Load

LLMs work within context limits. A broad skill that includes everything:

Consumes more context tokens
Creates decision fatigue (which guidance applies?)
Produces generic rather than specific advice

A focused skill:

Uses context efficiently
Provides clear, applicable guidance
Delivers specific, actionable recommendations

Composability

Focused skills compose better. You can load:

Python type checking skill
Python async patterns skill
Code review skill

Each contributes specific expertise without conflict. A single "Python everything" skill cannot combine with others as cleanly.

Defining Clear Purpose

The Single Responsibility Test

A skill should have one primary responsibility. Test with this question:

"What does this skill do?"

Good answers:

"Reviews Python code for type safety issues"
"Generates API documentation in OpenAPI format"
"Evaluates React components for accessibility"

Bad answers:

"Helps with code" (too vague)
"Reviews code and writes documentation and generates tests" (too many things)
"Handles Python and JavaScript and TypeScript" (too many domains)

If you cannot answer in one sentence, the skill is too broad.

Purpose Statement Format

Write an explicit purpose statement:

# [Skill Name]

## Purpose

This skill [action verb] [specific domain] by [method/approach].

**Primary focus:** [One thing]
**Secondary focus:** [Optional, closely related thing]
**Not covered:** [Explicit exclusions]

Example:

# React Performance

## Purpose

This skill evaluates React applications for performance issues
by analyzing component structure, render patterns, and state management.

**Primary focus:** Identifying unnecessary re-renders and optimization opportunities
**Secondary focus:** Suggesting performance-aware patterns
**Not covered:** General React patterns (see react-patterns skill), testing, accessibility

Scope Boundaries

Explicit boundaries prevent scope creep:

## Scope

### In Scope
- Component render optimization
- State management efficiency
- Memoization strategies
- Bundle size impact
- Virtual DOM considerations

### Out of Scope
- Business logic review
- API design
- Styling/CSS
- Testing strategies
- Accessibility (see react-accessibility skill)

### Boundary Cases
- State management patterns: In scope only for performance implications
- Data fetching: In scope for caching/revalidation, not for API design

Purpose Discovery

From Pain Points

What problems do you solve repeatedly?

Pain point: "I keep reviewing code and missing the same type issues"
Purpose: Type safety review skill

Pain point: "Documentation is inconsistent across teams"
Purpose: Documentation format skill

Pain point: "New hires make the same security mistakes"
Purpose: Security review skill for common vulnerabilities

From Expertise

What do you know that others need to learn?

Expertise: "I understand async Python deeply"
Purpose: Python async patterns skill

Expertise: "I know our API standards thoroughly"
Purpose: Company API standards skill

Expertise: "I spot performance issues quickly"
Purpose: Performance code review skill

From Repetition

What instructions do you type repeatedly?

Repetition: "Check for null safety, verify types, look for any usage"
Purpose: TypeScript strictness skill

Repetition: "Ensure error handling, validate input, check edge cases"
Purpose: Defensive coding skill

Repetition: "Use our commit format, include ticket numbers, sign off"
Purpose: Git workflow skill

Skill Scoping Techniques

Start Narrow, Expand Carefully

Begin with the smallest useful scope:

Iteration 1:

# Python Dict Type Hints

Type hints specifically for dictionary types in Python:
- TypedDict usage
- Generic dict patterns
- Dict vs Mapping

After success, consider if expansion is needed:

Iteration 2:

# Python Collection Type Hints

Type hints for Python collections:
- Lists, Sets, Dicts
- Sequence vs Collection vs Iterable
- Generic patterns

Only expand if the broader skill remains focused.

Split When Unclear

If purpose becomes unclear, split:

Before (unfocused):

# API Development

Design APIs, document them, test them, secure them...

After (split):

# API Design Patterns
RESTful design, resource modeling, versioning

# API Documentation
OpenAPI specs, endpoint documentation, examples

# API Security
Authentication, authorization, input validation

# API Testing
Contract testing, integration testing, mocking

Each resulting skill has clear purpose.

Depth Over Breadth

Prefer deep expertise in narrow area:

Shallow and broad:

# Security

- SQL injection
- XSS
- CSRF
- Auth issues
- Encryption
- [20 more topics...]

Deep and narrow:

# SQL Injection Prevention

## Understanding SQL Injection
- What it is
- How it works
- Why it is dangerous

## Detection
- Pattern recognition
- Dynamic SQL red flags
- ORM misuse patterns

## Prevention
- Parameterized queries
- ORM best practices
- Input validation layers

## Verification
- Testing for injection
- Code review checklist
- Automated scanning

## Examples
[Detailed examples for each database and ORM]

The deep skill provides more value for its specific domain.

Purpose Statement Examples

Good Purpose Statements

## Purpose: React Hook Dependencies

Analyze React hooks (useEffect, useMemo, useCallback) for
dependency array issues, including missing dependencies,
stale closures, and unnecessary dependencies.

## Purpose: Git Commit Messages

Guide creation of conventional commit messages that clearly
communicate the type, scope, and nature of changes following
the Conventional Commits specification.

## Purpose: Python Async Code Review

Evaluate Python async/await code for correctness and performance,
focusing on proper coroutine usage, avoiding blocking calls,
and efficient task management with asyncio.

Improved Purpose Statements

Before:

Help with testing.

After:

## Purpose: Pytest Unit Testing

Guide creation of effective pytest unit tests with emphasis on
test isolation, fixtures, parametrization, and meaningful assertions.
Focused on testing Python functions and classes, not integration or e2e.

Before:

Code review stuff.

After:

## Purpose: Security-Focused Code Review

Review code specifically for security vulnerabilities, including
injection flaws, authentication issues, authorization gaps,
and data exposure risks. Follows OWASP Top 10 as primary framework.

Testing Purpose Clarity

The User Test

Imagine a new team member reads your skill. Can they answer:

When should I use this skill?
What will it help me with?
What should I NOT use it for?

If any answer is unclear, refine the purpose.

The Non-Overlap Test

Compare with existing skills:

Does this skill duplicate another?
Is the boundary between skills clear?
Could requests go to either skill ambiguously?

If overlaps exist, clarify boundaries or merge skills.

The Output Test

Given the purpose, are expected outputs clear?

What kind of output will this skill produce?
In what format?
With what level of detail?

If outputs are unpredictable, the purpose may be too vague.

Documenting Purpose

Standard Sections

# [Skill Name]

## Purpose
One paragraph describing what this skill does.

## When to Use
- Situation 1
- Situation 2
- Situation 3

## When NOT to Use
- Situation 1 (use [X] instead)
- Situation 2 (use [Y] instead)

## What This Skill Provides
- Capability 1
- Capability 2

## What This Skill Does NOT Provide
- Out of scope 1
- Out of scope 2

## Related Skills
- [Skill A]: For [related purpose]
- [Skill B]: For [related purpose]

Example Documentation

# TypeScript Strict Mode

## Purpose
Evaluate TypeScript code for strict mode compliance and type safety,
identifying issues that would cause errors with strict flags enabled
and suggesting improvements for type-safe code.

## When to Use
- Migrating JavaScript to TypeScript
- Enabling strict mode on existing codebase
- Reviewing TypeScript PRs for type safety
- Learning TypeScript type system best practices

## When NOT to Use
- JavaScript-only codebases (no TypeScript)
- Questions about TypeScript build/config (see typescript-config skill)
- React-specific TypeScript patterns (see react-typescript skill)
- Node.js-specific TypeScript patterns (see node-typescript skill)

## What This Skill Provides
- Identification of `any` type usage that should be stricter
- Detection of missing null checks
- Suggestions for proper generic usage
- Recommendations for type guards and assertions
- Guidance on strict compiler options

## What This Skill Does NOT Provide
- General TypeScript tutoring
- Build configuration help
- Framework-specific patterns
- Performance optimization

## Related Skills
- react-typescript: TypeScript patterns specific to React
- typescript-config: tsconfig.json and build setup
- code-review: General code review (includes TypeScript)

Common Purpose Mistakes

Mistake: Feature Creep

# Python Review

Review Python code for style, types, performance, security,
testing, documentation, architecture...

Problem: Too many concerns, cannot excel at any.

Fix: Split into focused skills for each concern.

Mistake: Vague Scope

# Better Code

Help make code better.

Problem: No clear domain, audience, or output.

Fix: Define specific language, type of improvement, and context.

Mistake: Hidden Assumptions

# API Review

Review APIs for quality.

Problem: Which kind of API? REST? GraphQL? RPC? Internal? Public?

Fix: Make assumptions explicit: "Review REST APIs intended for public consumption."

Mistake: Missing Boundaries

# JavaScript Expert

Everything about JavaScript.

Problem: No boundaries, overlaps with many other skills.

Fix: Focus: "JavaScript async patterns" or "JavaScript testing with Jest."

Summary

Clear purpose is the foundation of effective skills. A well-defined purpose:

Focuses the skill on one thing done well
Sets expectations for what the skill provides
Defines boundaries to prevent scope creep
Enables composition with other skills
Guides users to appropriate usage

When designing skills:

Start narrow, expand only when proven valuable
Split unclear purposes into focused skills
Choose depth over breadth
Document purpose explicitly with when to use and when not to use
Test clarity with users and against overlaps

The result is skills that consistently deliver exceptional value for their specific domain.

Ready to inject domain context into your skills? Continue to Context Injection: Teaching AI Domain Knowledge for advanced context design.