Markdown skill creator

Markdown Skill Creator

Guide for creating effective markdown-only Claude Skills—skills that provide knowledge, guidance, and templates through Markdown content rather than executable scripts.

About Markdown-Only Skills

Markdown-only skills are ideal for:

• Knowledge Transfer: Domain expertise, company knowledge, standards
• Guidelines & Standards: Brand guidelines, code style, quality criteria
• Workflows & Processes: Multi-step procedures with decision points
• Templates: Communication formats, document structures, output templates
• Principles: Design philosophies, decision frameworks, quality standards

When to use markdown-only vs. scripts: See references/when-to-use.md

Skill Creation Process

Follow these steps to create an effective markdown-only skill:

Step 1: Understand the Skill Purpose

Start with concrete examples of how the skill will be used:

Ask clarifying questions:

• "What types of tasks should this skill handle?"
• "Can you provide examples of user requests that should trigger this skill?"
• "What knowledge or guidance would be most valuable?"
• "Are there existing documents or guidelines to incorporate?"

Example scenarios:

• "Help me write code review feedback" → code-review-guidelines skill
• "Generate customer support response" → support-templates skill
• "Apply brand colors to this design" → brand-guidelines skill

Step 2: Choose the Right Pattern

Based on the skill's purpose, select an appropriate pattern:

Available Patterns:

1. Guidelines & Standards - Style guides, brand guidelines, conventions
2. Workflow & Process - Multi-step procedures with decision points
3. Template Collection - Reusable output formats and structures
4. Domain Knowledge - Schemas, reference data, business logic
5. Principle-Based Guidance - Design philosophy, quality frameworks
6. Multi-Variant Reference - Supporting multiple frameworks or platforms

For detailed pattern templates: See references/patterns.md

Quick Selection Guide:

• Single set of standards? → Pattern 1 (Guidelines & Standards)
• Multi-step process? → Pattern 2 (Workflow & Process)
• Multiple output formats? → Pattern 3 (Template Collection)
• Large reference knowledge? → Pattern 4 (Domain Knowledge)
• Flexible guidance + quality criteria? → Pattern 5 (Principle-Based)
• Same concept, multiple variants? → Pattern 6 (Multi-Variant)

Step 3: Design the Structure

Simple Skills (under 500 lines):

skill-name/
└── SKILL.md (all content)

Skills with Progressive Disclosure:

skill-name/
├── SKILL.md (core guidance + navigation)
└── references/
    ├── domain-1.md
    ├── domain-2.md
    └── domain-3.md

Skills with Templates or Assets:

skill-name/
├── SKILL.md (guidance + navigation)
├── templates/ or references/
│   └── [template files]
└── assets/ (optional)
    └── [resources used in output]

Progressive Disclosure Principle:

• SKILL.md: Core guidance, navigation (~2-5k words, <500 lines)
• references/: Detailed information loaded only when needed
• assets/: Resources used in output (templates, fonts, images)

Step 4: Write Effective Frontmatter

The frontmatter determines when your skill triggers. This is critical.

---
name: skill-name
description: [What it does] + [When to use - comprehensive trigger list]
---

Description Best Practices:

• Include both what the skill provides AND when to use it
• List specific scenarios, file types, or tasks that trigger it
• Use multiple keywords and synonyms
• Be comprehensive—the description is the primary triggering mechanism

Examples:

❌ Too vague:

description: Helps with documents

✅ Comprehensive and specific:

description: Brand guidelines including colors, typography, and visual style for Anthropic's brand identity. Use when applying brand colors or style guidelines, visual formatting, company design standards, or when artifacts need Anthropic's look-and-feel.

✅ Lists all use cases:

description: Templates for customer communications including support responses, update notifications, incident communications, and feedback requests. Use when drafting customer-facing messages, responding to support tickets, or communicating service changes.

Step 5: Structure the SKILL.md Body

Core Sections:

1. Overview (1-2 paragraphs)

   • What the skill provides
   • Why it's valuable

2. Main Content (varies by pattern)

   • Guidelines, workflows, templates, or principles
   • Organized by pattern chosen in Step 2

3. Navigation (if using references/)

   • Clear pointers to reference files
   • When to load each reference

4. Examples (2-3 concrete examples)

   • Show the skill in action
   • Cover different use cases

Writing Guidelines:

• Use imperative/infinitive form ("Apply", "Generate", "Follow")
• Be concise—challenge each paragraph's token cost
• Provide concrete data, not verbose explanations
• Include anti-patterns and what to avoid
• Assume Claude is smart—only add non-obvious context

Step 6: Create Supporting Files

For references/:

• Detailed information Claude loads on-demand
• Organize by domain, variant, or use case
• Include table of contents for files >100 lines
• Reference clearly from SKILL.md

For assets/:

• Files used in output (templates, images, fonts)
• Not loaded into context
• Claude copies or uses them in generated output

For templates/:

• Often organized under references/ for progressive disclosure
• Each template should include:
  • When to use it
  • Required information
  • Template structure with placeholders
  • Multiple examples
  • Quality criteria

Step 7: Use Templates

Start with proven templates for common patterns:

Available Templates:

• assets/template-guidelines.md - For guidelines and standards skills
• assets/template-workflow.md - For workflow and process skills
• assets/template-collection.md - For template collection skills

Usage:

1. Copy the appropriate template
2. Replace [placeholders] with actual content
3. Customize sections to fit your specific needs
4. Delete template usage notes at the bottom

Step 8: Validate Quality

Before finalizing, check:

Frontmatter:

• Description is comprehensive and lists all trigger scenarios
• Description includes multiple keywords
• Name matches directory name (hyphen-case)

Content:

• SKILL.md under 500 lines (or split into references/)
• Concrete and actionable guidance
• Examples across different contexts
• Clear anti-patterns or common mistakes
• No verbose explanations of obvious concepts

Structure:

• Progressive disclosure if content is extensive
• References clearly linked from SKILL.md
• No extraneous files (README, CHANGELOG, etc.)
• Appropriate organization for the pattern chosen

Triggers:

• Test with example user requests
• Ensure description covers all intended use cases
• Keywords match how users would phrase requests

Best Practices

Conciseness

The context window is a public good. Only include information Claude doesn't already have.

Challenge each piece:

• "Does Claude really need this explanation?"
• "Does this paragraph justify its token cost?"

Prefer:

• Concise examples over verbose explanations
• Concrete data over abstract descriptions
• Specific guidance over general principles

Progressive Disclosure

Keep SKILL.md lean and load details only when needed:

1. Metadata (name + description): Always in context
2. SKILL.md body: Loaded when skill triggers
3. References: Loaded only when Claude needs them

Pattern Example:

## Advanced Features

For tracked changes in documents, see [references/tracked-changes.md](references/tracked-changes.md)

For OOXML internals, see [references/ooxml-details.md](references/ooxml-details.md)

Claude loads these references only when working with tracked changes or OOXML.

Concrete Examples

Examples are more valuable than explanations:

Instead of:

Brand colors should be applied consistently across all artifacts
while maintaining visual hierarchy and ensuring accessibility.

Provide:

## Brand Colors

- Dark: `#141413` - Primary text and dark backgrounds
- Orange: `#d97757` - Primary accent
- Blue: `#6a9bcc` - Secondary accent

Apply dark (`#141413`) for text, orange (`#d97757`) for CTAs and highlights.

Quality Standards

Include both what to do AND what to avoid:

## Quality Standards

Good API design demonstrates:
- Consistent naming (camelCase for JSON fields)
- Semantic HTTP status codes
- Comprehensive error messages

Avoid:
- Generic error messages ("Error occurred")
- Inconsistent field naming across endpoints
- Using GET for state-changing operations

Keywords and Triggers

Include a keywords section if helpful for discoverability:

**Keywords**: branding, corporate identity, visual identity, brand colors,
typography, visual design, style guidelines

Learning from Examples

For analysis of effective markdown-only skills:

• See references/examples.md for detailed breakdowns
• Study brand-guidelines, frontend-design, and internal-comms skills
• Notice patterns: concrete data + guidance, clear triggering, progressive disclosure

Common Mistakes to Avoid

1. Vague descriptions that don't trigger appropriately
2. Verbose explanations of concepts Claude already knows
3. Missing examples showing the skill in action
4. No anti-patterns or quality criteria
5. Deeply nested references making navigation complex
6. Extraneous files (README, CHANGELOG, installation guides)
7. Duplicated information between SKILL.md and references
8. Over-explaining instead of being concise and actionable

Advanced Techniques

Conditional Workflows

For skills with decision points:

## Workflow

1. **Identify the communication type**:
   - 3P update? → Load templates/3p-updates.md
   - Newsletter? → Load templates/newsletter.md
   - FAQ? → Load templates/faq.md

2. **Follow the template guidance** from the loaded file

Multi-Domain Organization

For skills covering multiple domains:

skill-name/
├── SKILL.md (overview + navigation)
└── references/
    ├── domain-1.md (loaded only for domain-1 queries)
    ├── domain-2.md (loaded only for domain-2 queries)
    └── domain-3.md (loaded only for domain-3 queries)

Assets for Output Quality

Include fonts, templates, or images that enhance output:

brand-skill/
├── SKILL.md
└── assets/
    ├── logo.png
    ├── presentation-template.pptx
    └── brand-fonts/

Claude uses these in generated output without loading them into context.

Resources

Reference Documentation

• references/examples.md - Detailed analysis of effective markdown-only skills
• references/patterns.md - Common patterns with templates and guidance
• references/when-to-use.md - Decision guide: markdown-only vs. script-based

Skill Templates

• assets/template-guidelines.md - Template for guidelines and standards skills
• assets/template-workflow.md - Template for workflow and process skills
• assets/template-collection.md - Template for template collection skills

Copy these templates as starting points and customize to your needs.

Quick Start Example

Creating a simple brand guidelines skill:

1. Understand: User wants to apply company brand colors and typography
2. Choose Pattern: Guidelines & Standards (Pattern 1)
3. Structure: Simple single-file SKILL.md
4. Frontmatter:

name: company-brand
description: Company brand guidelines including colors, typography, and visual style. Use when applying brand standards, visual formatting, or company design.

5. Content:
   • Overview of brand identity
   • Colors section with hex codes
   • Typography section with font specifications
   • Application guidance for different contexts
   • Examples showing brand application
6. Validate: Check description triggers appropriately, content is concise and actionable

Result: A functional markdown-only skill ready for use.