A skill that can't be found can't be used. Discovery optimization ensures that when a user or AI agent needs a specific capability, they can locate the right skill quickly. This skill covers naming conventions, tagging strategies, metadata design, and search optimization techniques that make skills discoverable through browsing, searching, and AI-assisted recommendation.

## Key Points

1. Agent receives a task
2. Agent searches available skills
3. Purpose section determines relevance
4. Agent loads most relevant skill(s)
1. Use the full term at least once, even if abbreviation is common:
2. Include common synonyms in the body:
3. Address common search queries in section headers:
4. Include error messages users might search for:
5. Reference related concepts that users might search adjacent:
6. Use technology names consistently:
- Naming a new skill file or skill pack
- Choosing tags for skill metadata

Skill Discovery Optimization

Purpose

A skill that can't be found can't be used. Discovery optimization ensures that when a user or AI agent needs a specific capability, they can locate the right skill quickly. This skill covers naming conventions, tagging strategies, metadata design, and search optimization techniques that make skills discoverable through browsing, searching, and AI-assisted recommendation.

Discovery Channels

How Skills Are Found

Discovery Methods (most to least common):
├── 1. Search query: User types keywords
│      └── Matches against: title, tags, body content
├── 2. Category browsing: User navigates skill packs
│      └── Matches against: category, directory structure
├── 3. AI recommendation: Agent selects relevant skill
│      └── Matches against: purpose, content, tags
├── 4. Cross-reference: Link from another skill
│      └── Follows: explicit mentions in skill body
├── 5. Curated list: Featured or top skills lists
│      └── Based on: quality rating, popularity, recency
└── 6. Direct link: Shared URL or CLI command
       └── Requires: knowing the skill exists already

Title Optimization

Naming Principles

Title Formula:
[Technology/Domain] + [Specific Aspect] + [Context if needed]

Good Titles:
├── "React Server Components with Next.js App Router"
│   └── Technology: React; Aspect: Server Components; Context: Next.js
├── "PostgreSQL Query Optimization for Large Tables"
│   └── Technology: PostgreSQL; Aspect: Query Optimization; Context: Large Tables
├── "Docker Multi-Stage Build Patterns"
│   └── Technology: Docker; Aspect: Multi-Stage Builds
├── "Git Branch Strategy for Small Teams"
│   └── Technology: Git; Aspect: Branch Strategy; Context: Small Teams
└── "REST API Error Handling Standards"
    └── Domain: REST API; Aspect: Error Handling

Bad Titles:
├── "React" — Too vague, which aspect?
├── "How to Make Your Database Faster" — Not searchable, informal
├── "Advanced Techniques Part 2" — Not descriptive, fragile ordering
├── "The Complete Guide to Everything" — Meaningless scope
└── "Stuff You Need to Know" — Not professional or searchable

Title Length:
├── Ideal: 4-8 words
├── Maximum: 12 words
├── Too short: Vague
└── Too long: Won't display fully in lists

Title Search Behavior

Users search with different intents:
├── Technology-first: "react hooks" → title should include "React Hooks"
├── Task-first: "how to deploy" → title should include "Deployment"
├── Problem-first: "slow queries" → title should include "Optimization"
└── Pattern-first: "observer pattern" → title should include pattern name

Match user mental models:
├── A backend developer searches "database" not "persistence layer"
├── A DevOps engineer searches "deploy" not "release management"
├── A beginner searches "how to" or "getting started"
└── An expert searches technology name + specific concept

Use standard terminology:
├── Use "Authentication" not "AuthN" in titles (search-friendly)
├── Use "REST API" not "RESTful Web Services" (more common search)
├── Use "Docker" not "Containerization" (technology name preferred)
└── Use well-known pattern names: "Observer", "Factory", "MVC"

Tag Strategy

Tagging Best Practices

Tag Categories:
├── Technology tags: Specific tools, languages, frameworks
│   └── "react", "postgresql", "docker", "typescript"
├── Concept tags: Abstract concepts covered
│   └── "performance", "security", "testing", "deployment"
├── Use-case tags: What task does this help with?
│   └── "debugging", "migration", "setup", "optimization"
├── Level tags: Difficulty/experience level
│   └── "beginner", "intermediate", "advanced"
└── Domain tags: Industry or domain relevance
    └── "web", "mobile", "devops", "data-engineering"

Tag Rules:
├── 3-8 tags per skill (too few = undiscoverable, too many = diluted)
├── Include obvious tags first (technology name)
├── Add 1-2 broader category tags
├── Add 1-2 specific aspect tags
├── Use lowercase, hyphenated multi-word tags
├── Be consistent across skill pack (same tag for same concept)
└── Avoid redundant tags (if title says "React", tag "react" is still useful
    but tag "react-framework" is redundant)

Example Tag Set:
Skill: "React Server Components with Next.js App Router"
Tags: ["react", "server-components", "nextjs", "ssr", "performance", "web"]
     ├── react: Technology
     ├── server-components: Specific concept
     ├── nextjs: Related technology
     ├── ssr: Architecture concept
     ├── performance: Benefit/use-case
     └── web: Broad domain

Tag Consistency

Maintaining Tag Vocabulary:

Create a controlled tag vocabulary for your skill pack:
├── Maintain a list of approved tags
├── Map synonyms to canonical tags:
│   ├── "js" → "javascript"
│   ├── "ts" → "typescript"
│   ├── "k8s" → "kubernetes"
│   ├── "postgres" → "postgresql"
│   ├── "ci-cd" → "ci/cd" (pick one, use consistently)
│   └── "auth" → "authentication"
├── Review new tags against existing vocabulary
└── Periodically audit and consolidate tags

Tag Frequency Guidelines:
├── A tag used by only 1 skill is likely too specific
├── A tag used by every skill in the pack is too generic
├── Ideal: Each tag matches 2-10 skills in a pack
└── Exception: Technology-specific tags may apply broadly

Purpose Section for Discovery

Writing for AI Recommendation

The Purpose section is the primary input for AI skill selection.

AI Agent Selection Process:
1. Agent receives a task
2. Agent searches available skills
3. Purpose section determines relevance
4. Agent loads most relevant skill(s)

Optimize Purpose for this process:

GOOD (AI can match to tasks):
"This skill covers configuring NGINX as a reverse proxy
for Node.js applications, including SSL termination,
load balancing, and WebSocket proxying. Use it when
deploying a Node.js app behind NGINX in production."

BAD (too vague for matching):
"This skill is about NGINX configuration."

BAD (too verbose for quick matching):
"In the modern landscape of web development, NGINX
has become an essential tool for... [3 more sentences
of context before getting to the point]"

Purpose Formula:
Sentence 1: What the skill covers (specific technologies + aspects)
Sentence 2: What it enables (outcome or capability)
Sentence 3 (optional): When to use it (context/scenario)

File Naming

File Name Conventions:
├── Use kebab-case: postgresql-query-optimization.md
├── Include key technology: react-hooks-patterns.md (not just hooks-patterns.md)
├── Be specific: docker-multi-stage-builds.md (not docker-advanced.md)
├── Match content: File name should approximate title
├── Avoid numbers for ordering: git-branching.md (not 03-git-branching.md)
├── No abbreviations unless universally known: rest-api.md is OK, ngnx.md is not
└── Extension: Always .md

File Name Should Be:
├── Predictable (if I know the topic, I can guess the filename)
├── Sortable (alphabetical ordering is useful)
├── Unique (no two skills should have the same name)
└── Stable (don't rename after publishing — breaks links)

Category and Pack Organization

Category Design for Discovery:
├── Use broad, recognizable categories
│   ├── GOOD: "react-skills", "devops-skills", "database-skills"
│   └── BAD: "frontend-stuff", "miscellaneous", "part-2"
├── Keep packs to 5-20 skills (browsable size)
├── Category name should be self-explanatory
├── Consistent naming pattern across all packs
└── Alphabetical listing should group related packs

Discovery-Friendly Pack Structure:
skills/
├── cloud-infrastructure/     ← Clear domain
│   ├── aws-lambda.md
│   ├── cloud-run.md
│   └── terraform-basics.md
├── frontend-frameworks/      ← Clear domain
│   ├── react-fundamentals.md
│   ├── vue-composition-api.md
│   └── svelte-basics.md
└── testing-strategies/       ← Clear concern
    ├── unit-testing.md
    ├── integration-testing.md
    └── e2e-testing.md

Search Optimization Techniques

Content Keywords

Embed searchable terms naturally in content:

1. Use the full term at least once, even if abbreviation is common:
   "Continuous Integration and Continuous Deployment (CI/CD)"

2. Include common synonyms in the body:
   "performance optimization (also known as performance tuning)"

3. Address common search queries in section headers:
   "### How to Debug Memory Leaks" — matches "how to debug memory leaks"

4. Include error messages users might search for:
   "If you see `ECONNREFUSED`, the database is not reachable"

5. Reference related concepts that users might search adjacent:
   "Unlike REST APIs, GraphQL uses a single endpoint..."
   — Shows up in GraphQL searches and REST searches

6. Use technology names consistently:
   Write "PostgreSQL" not "the database" throughout
   — Search for "PostgreSQL" finds every mention

Anti-Patterns

Discovery Anti-Patterns:
✗ Clever or cute names: "The Ninja's Guide to CSS" — not searchable
✗ Generic titles: "Best Practices" — matches everything and nothing
✗ Internal codenames: "Project Phoenix Setup" — means nothing outside
✗ Overly long titles: "A Comprehensive and Thorough Guide..." — truncated in UI
✗ Missing tags: Rely on title alone — limits search dimensions
✗ Inconsistent terminology: "Kubernetes" here, "K8s" there — missed searches
✗ Missing Purpose section: AI agents can't determine relevance
✗ Buried key terms: Main technology name not in first 50 words

When to Apply This Skill

Use this skill when:

• Naming a new skill file or skill pack
• Choosing tags for skill metadata
• Writing the Purpose section of a skill
• Reviewing skills for discoverability issues
• Planning the organization of a skill repository
• Optimizing existing skills that have low discovery rates