ansible-markdown-docs

name	ansible-markdown-docs
description	Fetch Ansible documentation from docs.ansible.com as Markdown. Use when the user asks about an Ansible topic, references a docs.ansible.com URL, or when the agent needs to look up official Ansible documentation to complete a task or verify information.
user-invocable	true
triggers	["get ansible documentation","docs.ansible.com","fetch ansible docs","show ansible documentation","look up ansible docs"]

Skill: ansible-markdown-docs

Purpose

Fetch a page from docs.ansible.com as Markdown and use its content as context — either to answer a user question or to inform the agent's own reasoning during a task. The raw Markdown is context for the agent — do not dump it directly at the user.

When to Invoke

TRIGGER when:

• The user asks about an Ansible topic that warrants looking up official documentation
• The user provides a docs.ansible.com URL
• The user asks to "look up", "find", or "check" something in the Ansible docs
• The agent needs to verify Ansible behaviour, syntax, or requirements while completing a task
• Another skill or workflow requires authoritative Ansible documentation as input

DO NOT TRIGGER when:

• The documentation needed is not on docs.ansible.com
• The question can be answered from existing context without fetching a page

Inputs

• url (optional): A full https://docs.ansible.com/... URL. If omitted, the skill searches for the best matching page based on the user's topic.

Prerequisites

• curl available in PATH
• Web search available for resolving topic descriptions to URLs. If web search is unavailable, ask the user to provide a direct docs.ansible.com URL.

Workflow

Step 1 — Resolve the URL

If the user provided a docs.ansible.com URL, use it directly and skip to Step 2.

If the user described a topic (e.g. "Ansible community package collections requirements"), perform a web search scoped to docs.ansible.com to find the most relevant page:

• Search query: site:docs.ansible.com <topic>
• Select the most relevant result URL
• If no confident match is found, ask the user to clarify or provide a URL directly

Step 2 — Validate the URL

Ensure the resolved URL begins with https://docs.ansible.com/. If it does not, refuse:

"I can only fetch pages from docs.ansible.com. Please provide a valid URL or rephrase your topic so I can find the right page."

Step 3 — Fetch the documentation

Run:

curl -s -m 30 <url> -H "Accept: text/markdown"

The Accept: text/markdown header instructs docs.ansible.com (powered by Read the Docs) to return the page content as Markdown instead of HTML.

Step 4 — Handle the response

Success: Use the returned Markdown as context to answer the user's question. Summarise, quote relevant sections, and explain — do not paste the raw Markdown in full.

Empty or HTML response: If the response starts with <!DOCTYPE or <html, or is empty, try an alternative URL from the search results. If all attempts fail, inform the user:

"I wasn't able to retrieve that page as Markdown. Try providing the exact docs.ansible.com URL directly."

curl error: Report the error and suggest checking network connectivity or the URL.

Step 5 — Answer conversationally

Use the fetched content to directly address what the user asked. For example:

• "Look up the Ansible community package collections requirements" → fetch the relevant page, then summarise the requirements clearly
• "What does the playbooks intro say about plays?" → fetch the playbooks intro page, then quote and explain the relevant section

Offer to fetch related pages or dig deeper if the answer is incomplete.

Example Interactions

Example 1: URL provided

User: "Get the docs at https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html"

Step 1: URL provided — use directly.
Step 2: Validate ✓
Step 3: curl -s -m 30 <url> -H "Accept: text/markdown"
Step 4: Use content as context.
Step 5: Summarise and answer.

Example 2: Topic description

User: "Look up the Ansible community package collections requirements"

Step 1: No URL — search site:docs.ansible.com ansible community package collections requirements
        → resolves to e.g. https://docs.ansible.com/ansible/latest/community/collection_contributors/collection_requirements.html
Step 2: Validate ✓
Step 3: curl -s -m 30 <url> -H "Accept: text/markdown"
Step 4: Use content as context.
Step 5: Answer: "According to the Ansible docs, community package collections must meet the
        following requirements: ..."

Notes

• Always use curl -s -m 30 (silent mode with 30-second timeout) to suppress progress output and prevent hangs on network issues.
• The fetched Markdown is agent context — synthesise from it, do not print it verbatim.
• Only fetch from docs.ansible.com; validate before every request.
• NEVER truncate the fetched content. Process the full response regardless of length. If the content is large, save it to a temporary file and reference the path rather than truncating or summarising prematurely.
• NEVER pipe the curl command to head or any other truncating command. Always capture the full output and write it to a temporary file if needed.