# Markdown Skill Creator

> Guide for creating effective markdown-only Claude Skills that function without executable scripts. Use when creating skills based on knowledge, guidelines, templates, workflows, or domain expertise. Covers structure, patterns, best practices, and provides templates for common skill types (guidelines, workflows, template collections, domain knowledge, principles-based guidance).

- Skill: `kongyo2/markdown-skill-creator` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add kongyo2/markdown-skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kongyo2/markdown-skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kongyo2 (https://skillmd.com/u/kongyo2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kongyo2/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](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](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.

```yaml
---
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**:
```yaml
description: Helps with documents
```

✅ **Comprehensive and specific**:
```yaml
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**:
```yaml
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**:
```markdown
## 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**:
```markdown
Brand colors should be applied consistently across all artifacts
while maintaining visual hierarchy and ensuring accessibility.
```

**Provide**:
```markdown
## 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:

```markdown
## 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:

```markdown
**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](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:

```markdown
## 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](references/examples.md)** - Detailed analysis of effective markdown-only skills
- **[references/patterns.md](references/patterns.md)** - Common patterns with templates and guidance
- **[references/when-to-use.md](references/when-to-use.md)** - Decision guide: markdown-only vs. script-based

### Skill Templates

- **[assets/template-guidelines.md](assets/template-guidelines.md)** - Template for guidelines and standards skills
- **[assets/template-workflow.md](assets/template-workflow.md)** - Template for workflow and process skills
- **[assets/template-collection.md](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**:
```yaml
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.