Advanced Example Skill

This skill demonstrates all available metadata fields and shows how to organize a complex skill with multiple subdirectories, examples, and templates.

Complete Folder Structure

advanced-example/
├── SKILL.md              ← This file with full metadata
├── examples/             ← Example files directory
│   ├── example1.py       ← Python example
│   └── example2.txt      ← Text example
├── templates/            ← Template files directory
│   └── template.txt      ← Template file
└── README.md             ← Additional documentation (optional)

All Metadata Fields Explained

Required Fields

• name: Unique identifier (kebab-case recommended)
• description: Brief, clear description of what the skill does

Version and Authorship

• version: Semantic version (MAJOR.MINOR.PATCH)
• author: Creator's name or team
• created: Creation date (ISO format: YYYY-MM-DD)
• updated: Last update date (ISO format)

Dependencies

You can specify dependencies in two formats:

Nested format (recommended for categorized deps):

dependencies:
  python: ["package>=1.0.0", "another-package"]
  system: ["git", "curl"]

Flat format (simpler):

dependencies: ["package1", "package2", "tool1"]

Categorization and Discovery

• category: Main category for grouping (e.g., "data-analysis", "document-creation")
• tags: Array of tags for search and filtering
• complexity: Difficulty level ("beginner", "intermediate", or "advanced")

Usage Guidance

• when_to_use: Array of scenarios when this skill should be used
• related_skills: Array of related skill names for cross-referencing

Examples

• has_examples: Boolean flag indicating if examples are included
• example_files: Array of paths to example files (relative to skill folder)

Dependency Management

The server supports tracking dependencies so users know what's required:

Python Dependencies

dependencies:
  python: ["pydantic>=2.0.0", "numpy>=1.20.0"]

System Dependencies

dependencies:
  system: ["git", "curl", "jq"]

Mixed Dependencies

dependencies:
  python: ["requests>=2.28.0"]
  system: ["ffmpeg"]
  node: ["typescript"]

Using When-To-Use

The when_to_use field helps Claude understand when to apply this skill:

when_to_use:
  - "When working with complex data transformations"
  - "When you need to generate reports from structured data"
  - "When combining multiple data sources"

Related Skills

Link to other skills to build a knowledge graph:

related_skills: ["data-cleaning", "visualization-basics", "export-formats"]

Organizing Example Files

Examples Directory

Place working examples that demonstrate the skill:

• Code samples (.py, .js, .go, etc.)
• Data files (.json, .csv, .xml)
• Configuration files

Templates Directory

Include reusable templates:

• File templates
• Code boilerplates
• Configuration templates

Referencing Examples in Content

You can reference your examples in the markdown content:

• See examples/example1.py for a working implementation
• Check templates/template.txt for the base template
• Review examples/example2.txt for sample data format

Hot-Reload Support

When hot-reload is enabled, any changes to this SKILL.md file will be automatically detected and the skill will be reloaded without restarting the server!

Try it:

1. Edit this file
2. Save it
3. Watch the server logs - you'll see the reload happening

Advanced Features

Complexity Levels

• beginner: Basic skills, minimal prerequisites
• intermediate: Requires some background knowledge
• advanced: Complex skills with multiple dependencies

Category Organization

Skills are grouped by category in the catalog. Choose descriptive categories:

• document-creation
• data-analysis
• automation
• web-scraping
• etc.

Tag Best Practices

Use lowercase tags, be specific but not too narrow:

• Good: ["excel", "formulas", "automation"]
• Avoid: ["Excel", "EXCEL_FORMULAS", "automation-tool"]

Validation

The server validates: ✓ Folder structure (skill must be in dedicated folder) ✓ Required fields (name, description) ✓ YAML syntax ✓ File references (example files must exist) ✓ Complexity values (must be beginner/intermediate/advanced)

Best Practices Summary

1. One skill per folder - Each skill in its own directory
2. Meaningful names - Use descriptive, kebab-case names
3. Complete metadata - Fill in as many fields as applicable
4. Organize files - Use subdirectories (examples/, templates/, docs/)
5. Version your skills - Use semantic versioning
6. Document dependencies - Be explicit about requirements
7. Provide examples - Working examples are invaluable
8. Use tags wisely - Make skills discoverable
9. Link related skills - Build a knowledge graph
10. Keep it updated - Update the updated field when you make changes

Conclusion

This advanced example demonstrates the full power of the MCP Skills Server's metadata system. You can use as many or as few of these fields as needed for your specific use case.

Start simple with minimal-example, grow with intermediate-example, and reference this advanced-example when you need the full feature set!