How to Write SKILL.md and Tool Descriptions in Markdown for AI Agents

AI assistants become more useful when they can follow stable instructions, load domain knowledge, and use tools safely. Markdown is a practical format for that layer because it is readable, easy to version, and structured enough for both people and models.

This article explains how to write Markdown-based SKILL.md files, agent instruction files, and tool use descriptions. The goal is not to make prompts longer. The goal is to make capabilities easier for an AI agent to discover, understand, and apply at the right time.

What Is a SKILL.md File?

A SKILL.md file is a Markdown instruction file that describes a reusable capability. In Claude Code, skills are filesystem artifacts stored in a skills directory, and each skill is defined by a SKILL.md file. The same idea appears across agent systems even when the exact file name differs: a small, structured document tells the agent when to use a capability, what workflow to follow, and where supporting scripts or references live.

The useful mental model is simple:

• A normal prompt tells the AI what to do now.
• A skill tells the AI how to do a class of tasks repeatedly.
• A tool description tells the AI when and how to call a specific external function or service.

Markdown is a good fit because a skill is mostly instruction, examples, constraints, and links to supporting files.

Why Markdown Works Well for Agent Skills

Agent instructions must serve two readers: the AI model and the human maintainer. Markdown supports both.

For the AI, headings and lists separate trigger conditions, steps, constraints, examples, and fallback behavior. For humans, the same file can be reviewed in Git, edited in any text editor, and documented alongside code.

This is especially important for skills and tools because unclear instructions can cause real workflow errors. A vague skill may be used at the wrong time. A vague tool description may lead the model to call a tool with the wrong arguments. A missing safety note may cause the agent to act before it has enough evidence.

The Difference Between Skills and Tool Descriptions

Skills and tools are related, but they are not the same.

| Item | Purpose | Example | |---|---|---| | Skill | Teach a reusable workflow or domain procedure | "How to review a pull request" | | Tool description | Tell the model what a callable function does and when to use it | "Search GitHub issues by query" | | System prompt | Set broad behavior for the assistant | "Be concise and verify claims" | | Project instruction file | Explain local repo conventions | "Use pnpm and do not run build" |

OpenAI's function calling and Agents SDK documentation describe tools as a way for models or agents to fetch data, call external APIs, execute code, or access capabilities outside the model itself. The Agents SDK guidance recommends short, explicit tool descriptions that explain what the tool does and when to use it. That same principle applies to Markdown skills: be explicit about purpose and activation.

A Practical SKILL.md Structure

A useful skill file should answer six questions:

1. What capability does this skill provide?
2. When should the agent use it?
3. When should the agent avoid it?
4. What steps should the agent follow?
5. What files, scripts, or references are available?
6. What should the final output look like?

Here is a practical template:

---
name: markdown-conversion-review
description: Use this skill when reviewing or improving Markdown converted from documents, PDFs, HTML, or office files.
---

# Markdown Conversion Review

## Use This Skill When
- The user asks to clean up converted Markdown.
- The user wants a document prepared for README, docs, blog, or AI prompt usage.
- The source content contains tables, headings, links, code blocks, or lists that may need repair.

## Do Not Use This Skill When
- The user only asks for a brief explanation of Markdown syntax.
- The task requires editing source files outside the provided document.

## Workflow
1. Inspect the converted Markdown for broken hierarchy, malformed tables, lost links, and code fence problems.
2. Preserve the author's meaning and original order unless the user asks for rewriting.
3. Normalize headings, lists, links, and tables using simple Markdown.
4. Flag any source formatting that cannot be recovered reliably.
5. Return the cleaned Markdown and a short change note.

## Quality Bar
- Do not invent missing content.
- Keep code blocks exact unless the user asks for formatting.
- Prefer readable Markdown over complex embedded HTML.

## Output Format
Return:
1. Cleaned Markdown
2. Notes
3. Any unresolved issues

The frontmatter fields depend on the agent system you use, so check that system's documentation. The body pattern is portable: triggers, exclusions, workflow, quality bar, and output format.

How to Write the Description Field

The description is often the most important part of a skill or tool. It is the short text the agent may use to decide whether the capability is relevant.

Weak description:

description: Helps with Markdown.

Better description:

description: Use this skill when the user needs converted Markdown cleaned, normalized, or prepared for documentation, README files, blogs, or AI prompts.

The better version includes:

• The trigger: "when the user needs..."
• The action: "cleaned, normalized, or prepared"
• The domain: "converted Markdown"
• The likely outputs: "documentation, README files, blogs, or AI prompts"

How to Write Tool Use Descriptions

Tool descriptions should be shorter than skills. A tool is a specific operation, so the model needs a crisp answer to three questions:

• What does the tool do?
• When should it be used?
• What inputs does it require?

Example:

{
  "name": "convert_file_to_markdown",
  "description": "Convert an uploaded PDF, DOCX, PPTX, XLSX, HTML, or image file into Markdown when the user wants editable text or AI-ready document content.",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "The uploaded file identifier to convert."
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "Whether to preserve tables as Markdown tables when possible."
      }
    },
    "required": ["file_id"]
  }
}

The description does not say "use this for everything." It names the supported file types and the user's intent. The parameter descriptions are also specific. Good tool use descriptions reduce unnecessary calls and improve argument quality.

A Markdown Pattern for Tool Documentation

If you document tools for an agent in Markdown, use a predictable structure:

# Tool: convert_file_to_markdown

## Purpose
Convert supported document files into Markdown.

## Use When
- The user uploads a file and asks for Markdown.
- The user wants document content prepared for an LLM, README, docs page, or blog.

## Do Not Use When
- The user only asks a conceptual question about Markdown.
- The input is already clean Markdown and no conversion is needed.

## Inputs
| Name | Type | Required | Notes |
|---|---|---:|---|
| file_id | string | Yes | Uploaded file identifier |
| preserve_tables | boolean | No | Preserve tables when possible |

## Output
Markdown text plus conversion notes.

## Failure Handling
- If the file type is unsupported, explain the supported formats.
- If layout cannot be preserved, return the best text extraction and note the limitation.

This is useful when tool definitions live in code but the agent also needs human-readable operating guidance.

What Makes a Skill Actually Useful?

A good skill is operational. It should help the agent make decisions during a real task.

1. Clear Activation

Tell the agent when the skill applies. Do not rely on a broad title.

Weak:

# SEO Skill

Better:

## Use This Skill When
- The user asks to improve a page for search quality.
- The content needs title, description, headings, internal links, or FAQ improvements.
- The user mentions E-E-A-T, helpful content, or low-quality content issues.

2. Explicit Non-Goals

Non-goals prevent misuse.

## Do Not Use This Skill When
- The user asks for legal, medical, or financial advice.
- The task requires fabricating testimonials, statistics, citations, or reviews.
- The page topic is unrelated to the product or user intent.

This is important for trust. A skill should not push an agent toward content that looks optimized but is inaccurate.

3. A Step-by-Step Workflow

A skill should include a workflow that can be followed under pressure.

## Workflow
1. Identify the user's target audience and search intent.
2. Check whether the content answers a real user problem.
3. Improve headings so each section has a clear purpose.
4. Add examples, caveats, and source links where they improve trust.
5. Remove vague claims, filler, and keyword stuffing.

The steps should be specific enough to guide behavior, but not so detailed that the skill becomes brittle.

4. Examples of Good and Bad Output

Examples are often more useful than adjectives.

## Style Example

Avoid:
"Our revolutionary converter guarantees flawless results for every document."

Prefer:
"The converter extracts document content into Markdown and works best when the source file has clear headings, tables, and text-based content."

The preferred version is more trustworthy because it describes value and limitation together.

5. Safety and Permission Boundaries

Agent skills sometimes point to scripts, APIs, or local tools. If a skill can cause side effects, document boundaries clearly:

## Safety
- Read files before editing them.
- Do not delete user files unless the user explicitly asks.
- Ask before sending data to external services.
- Do not run build or deployment commands unless the project instructions allow it.

This kind of section is especially useful in coding agents and automation workflows.

SKILL.md Template for AI Capability Design

Use this template as a starting point:

---
name: skill-name
description: Use this skill when {specific trigger, task type, and domain}.
---

# Skill Name

## Purpose
{One paragraph explaining the capability and user value.}

## Use This Skill When
- {Trigger}
- {Trigger}
- {Trigger}

## Do Not Use This Skill When
- {Non-goal}
- {Non-goal}

## Inputs to Look For
- {Input type}
- {Input type}

## Workflow
1. {First concrete step}
2. {Second concrete step}
3. {Third concrete step}
4. {Verification or output step}

## Quality Bar
- {Accuracy rule}
- {Completeness rule}
- {Trust or safety rule}

## Available References
- `references/example.md`: {when to open it}
- `scripts/helper.py`: {when to run it}

## Output Format
{Describe the final answer or artifact.}

## Failure Handling
- If {problem}, then {response}.
- If {problem}, then {response}.

Common Mistakes in Skills and Tool Descriptions

Mistake 1: Overloading One Skill

One skill should cover one coherent capability. A single "marketing skill" that includes SEO, analytics, copywriting, ad policy, image generation, and email outreach will be hard for an agent to use correctly.

Split skills by workflow when the activation rules differ.

Mistake 2: Writing Aspirational Instructions

Avoid instructions such as "be world-class" or "make it amazing." They do not tell the agent what to do.

Use observable requirements instead:

• Include source links for factual claims.
• State assumptions when information is missing.
• Preserve user-provided terminology.
• Return unresolved risks separately.

Mistake 3: Hiding Critical Rules in Long Paragraphs

Use lists for rules that matter. If a rule is important enough to affect behavior, make it easy to find.

Mistake 4: Missing Failure Behavior

Tools fail. Inputs are incomplete. Files may be unsupported. A skill should tell the agent what to do next.

## Failure Handling
- If conversion loses table structure, return the extracted text and explain which table could not be reconstructed.
- If a required input is missing, ask one concise question.
- If the source is too large, summarize the limitation and process the highest-priority section first.

Final Thoughts

Markdown-based skills and tool descriptions are a practical way to give AI agents more capability without hiding behavior inside vague prompts. The best files are short, specific, and operational. They define when to use a capability, how to apply it, what to avoid, and how to handle failure.

If you are building AI workflows around Markdown conversion, documentation, or prompt libraries, SKILL.md files can become a maintainable bridge between human process knowledge and agent behavior.

Sources and Further Reading

• Claude Docs: Agent Skills
• Claude Code Docs: Agent SDK Skills
• OpenAI API: Function calling
• OpenAI Agents SDK: Tools
• OpenAI Agents SDK for Python: Tools
• Anthropic Docs: Use XML tags to structure your prompts