markdown

name	markdown
description	This skill should be used when the user asks to 'generate Markdown', 'create documentation', 'structure content', or 'format skill definitions'. Covers Markdown generation and structured documentation patterns.
version	1.0.0
metadata	{"internal":false}

Markdown Generation

Guides structured Markdown generation for skill definitions, documentation, and AI-optimized content following rumpleskill conventions.

Capabilities

• YAML Frontmatter: Structured metadata for skill files with required fields
• Skill Definition Format: Standardized .md structure for AI consumption
• Code Block Formatting: Language-specific fenced code blocks with proper indentation
• Structured Sections: Consistent heading hierarchy and section organization
• Token-Efficient Content: Dense, high-signal documentation without verbose explanations

Input Requirements

For skill generation:

• Skill name (kebab-case)
• Trigger phrases (action verbs users would say)
• Project-specific patterns from codebase analysis
• Technology stack context from AGENTS.md

Patterns

YAML Frontmatter (Required)

---
name: my-skill-name
description: This skill should be used when the user asks to 'action one', 'action two', or 'action three'. Brief capability summary.
version: 1.0.0
metadata:
  internal: false
---

Rules:

• name MUST be kebab-case (lowercase with hyphens)
• description MUST start with "This skill should be used when the user asks to"
• Include quoted trigger phrases users would naturally say
• metadata.internal determines visibility (false = user-facing)

Skill Section Structure

# Skill Title

One-paragraph introduction.

## Capabilities

- **Feature**: Description
- **Feature**: Description

## Patterns

### Pattern Name

```language
// Actual project code
```

Explanation of when/how to use.

Best Practices

1. Project-specific convention
2. Another convention

Limitations

• Honest constraints
• Edge cases

**Keep under 200 lines** - remove empty sections, be concise.

### Code Blocks

```typescript
// GOOD: Project-specific, copy-paste ready
import { callClaude } from "../utils/claude.js";

export async function generateMySkill(): Promise<string> {
  const context = await gatherContext();
  return await callClaude(PROMPT, context);
}

Rules:

• Always specify language after opening fence
• Use actual file paths from the project when possible
• Show real patterns, not toy examples
• Include ESM .js extensions in TypeScript imports

Table Formatting

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Value    | Value    | Value    |

Use tables for:

• Environment variables
• Command references
• Configuration options

List Conventions

## Unordered (Features/Capabilities)

- **Bold Label**: Description text
- **Bold Label**: Description text

## Ordered (Workflows/Steps)

1. **Action**: Explanation
2. **Action**: Explanation

## Nested (Complex Patterns)

- Top level
  - Sub-item with 2-space indent
  - Another sub-item

Best Practices

1. Token Efficiency: Ask "Does Claude need this?" before adding explanations
2. Project Context: Reference actual files, functions, and patterns from the codebase
3. Trigger Phrases: Use verbs users would naturally say ("create a component", "fix types")
4. No Generic Content: Avoid explaining what React/TypeScript/Node is - Claude knows
5. Code Over Prose: Show patterns with code examples, not paragraphs
6. Kebab-Case Names: All skill names lowercase with hyphens (tanstack-query, not TanStackQuery)

Common Pitfalls

• Missing Trigger Phrases: Description must include "when the user asks to [actions]"
• Wrong Name Format: Using camelCase or Title Case instead of kebab-case
• Verbose Explanations: Adding content Claude already knows wastes tokens
• Generic Examples: Showing toy code instead of project-specific patterns
• Empty Sections: Include only sections with meaningful content

Limitations

• Markdown is for AI consumption - optimize for Claude, not human readability
• Cannot include interactive elements or dynamic content
• YAML frontmatter must be valid - syntax errors break parsing
• Code blocks cannot be nested within code blocks
• Table formatting requires consistent column alignment

References

• GitHub Flavored Markdown (CommonMark spec)
• YAML 1.2 specification for frontmatter
• src/prompts/skill-template.ts - Template used by this project's generator