← Back to Guides

Meta Guide

How the guide-research-html-publish Skill Works (03/27/26)

This is the operational map for how the skill processes a guide request from start to finish: intake, framing, research, composition, HTML construction, organization, index updates, and final publish to awheatsandbox.com. It is written for Alan as the future skill editor/maintainer.

1

End-to-End Overview

The skill is effectively a production pipeline. It takes a user request and turns it into a published, indexed, and navigable guide artifact.

  1. Request intake: parse what the user wants, who it is for, and where it should publish.
  2. Framing: define target outcome, audience level, assumptions, and one preferred execution path.
  3. Research: gather only needed facts (prereqs, exact steps, expected outputs, failure modes).
  4. Composition: structure content in a predictable sequence that is skimmable and action-oriented.
  5. HTML conversion: apply template + metadata + section structure for standalone rendering.
  6. Organization: set category/subcategory/slug/path + optional related-guide links.
  7. Publishing: update index, upload guide and index to sandbox FTP, verify links.
Mental model: treat the skill like a mini static-site build system for one guide at a time.
2

How Requests Are Received

Input is a natural-language request (usually from the main agent/user) that asks for a guide to be created and published.

Signal extraction from request

  • Topic + desired end result
  • Audience (beginner/intermediate/advanced)
  • Output format (standalone HTML expected)
  • Publishing target (sandbox site path)
  • Index update requirement

If request is ambiguous

  • Infer a single primary path (avoid multiple branching workflows)
  • Default to explicit prerequisites and exact paths
  • Prefer clarity over cleverness

In this case, the request is itself “meta”: explain this skill’s own internal workflow in detail.

3

How the Skill Frames the Guide

Before writing anything substantial, the skill fixes four anchors:

  • Outcome: what the reader can do after reading.
  • Audience level: how much prior context is assumed.
  • Environment assumptions: versions, tools, filesystem paths, account access.
  • One recommended path: the default route, with alternatives only if necessary.
For this guide: outcome = “Alan can tweak/maintain the skill confidently without guessing how each phase works.”
Frame ElementExample in this meta-guide
OutcomeUnderstand request-to-publish lifecycle of the skill
AudienceAlan (maintainer/editor), intermediate technical comfort
AssumptionsOpenClaw workspace access, skill files present, ftp upload script usable
Preferred pathSingle pipeline: draft → metadata → index update → upload → verify
4

Research Layer: Tools, Priorities, What Gets Saved

The skill does targeted research, not broad internet scraping. Priority order is:

  1. Local skill files first (source of truth): SKILL.md, template HTML, helper scripts.
  2. Companion skill files when needed (for publish mechanics).
  3. Web search only when external tool/version facts are required.

What is extracted during research

  • Required sections and sequence rules
  • Metadata schema + required keys
  • Index update command and duplicate behavior
  • Publish command and destination path pattern
  • Verification expectations
Important: the guide should save the decision-relevant facts, not every discovered detail. Keep signal, drop noise.
5

How Composition/Structure Decisions Are Made

The skill defaults to a stable narrative shape so readers can scan quickly:

  1. Title (with MM/DD/YY date in title text)
  2. Outcome summary
  3. Prerequisites
  4. Required tools/files
  5. Step-by-step process
  6. Validation checks
  7. Troubleshooting
  8. Sources

For a meta-guide like this one, the same logic is preserved, but section names are tuned to explain internals (intake, framing, research, organization, publish).

Style rules enforced

  • Short paragraphs
  • Numbered actions
  • Bulleted checklists
  • monospace for exact names/paths/commands

Style rules avoided

  • Long intro essays
  • Vague words (“just”, “obviously”)
  • Mixing required vs optional steps
  • Unranked alternatives
6

How the Skill Turns Content into HTML

The skill starts from assets/guide-template.html unless a different style is requested. The final guide must be standalone (no build pipeline dependency).

HTML assembly pattern

  1. Set document <title> with dated guide title.
  2. Inject <script type="application/json" class="guide-metadata"> block in <head>.
  3. Render hero + concise lede.
  4. Build navigable sections with stable anchors.
  5. Add callouts for tips/warnings/success checks.
  6. Include Sources and Related Guides sections.

Required metadata keys

title, description, category, subcategory, tags, difficulty, status, featured, lastUpdated, slug.

{
  "title": "How the guide-research-html-publish Skill Works (03/27/26)",
  "category": "Operations & Process",
  "subcategory": "Administrative Workflows",
  "slug": "guide-research-html-publish-skill-workflow",
  "status": "published",
  "lastUpdated": "2026-03-27"
}
7

Organization: Categories, Slugs, Paths, Related Guides

After content exists, the skill runs the organizational layer.

  1. Determine primary user outcome
  2. Assign category + subcategory
  3. Generate clean slug (lowercase, hyphenated)
  4. Place file in guide path structure
  5. Add related-guide links where genuinely relevant

Decision in this guide: categorized as Operations & Process / Administrative Workflows because the main value is process execution, not AI model behavior.

Path note: New guides can use nested structure /public/guides/{category}/{subcategory}/{slug}.html, but flat /public/guides/*.html links remain common in the current index. Use whichever matches the active publishing convention for the site.
8

Publishing: Index Update + ftp-publish-sandbox

Publishing is a two-file release: (1) new guide HTML, (2) updated guides index HTML.

Step A: update local guides index

python3 /Users/alanwheat/.openclaw/workspace/skills/guide-research-html-publish/scripts/update_guides_index.py \
  --index /Users/alanwheat/.openclaw/workspace/docs/_ftp_guides_index.html \
  --title "How the guide-research-html-publish Skill Works (03/27/26)" \
  --href "/public/guides/guide-research-html-publish-skill-workflow-2026-03-27.html"

The helper script prevents duplicate href entries.

Step B: upload guide + index via FTP publish skill

/Users/alanwheat/.openclaw/workspace/skills/ftp-publish-sandbox/scripts/upload.sh \
  /Users/alanwheat/.openclaw/workspace/docs/public/guides/guide-research-html-publish-skill-workflow-2026-03-27.html \
  guides/guide-research-html-publish-skill-workflow-2026-03-27.html

/Users/alanwheat/.openclaw/workspace/skills/ftp-publish-sandbox/scripts/upload.sh \
  /Users/alanwheat/.openclaw/workspace/docs/_ftp_guides_index.html \
  guides/index.html

Step C: verify

  • Upload command exits successfully
  • Local index contains the new href
  • Public URLs load:
    • https://awheatsandbox.com/public/guides/guide-research-html-publish-skill-workflow-2026-03-27.html
    • https://awheatsandbox.com/public/guides/index.html
9

Practical Maintainer Checklist (Alan Edition)

  1. Read skill SKILL.md + template + index-update script.
  2. Define outcome/audience/assumptions in 4 bullets.
  3. Draft guide with one recommended path.
  4. Add metadata JSON in head with complete required fields.
  5. Set title with date in MM/DD/YY.
  6. Save under docs/public/guides/ using slugged filename.
  7. Run index update script with canonical published href.
  8. Upload guide and _ftp_guides_index.html via ftp publish script.
  9. Open both live URLs and spot-check navigation + formatting.