hip-tutorial-builder

HIP Tutorial Builder Skill

Foundation exemption: Inherits the tutorial-builder exemption. Tutorial skills use code-execution quality gates (verify-and-fix loops, milestone acceptance criteria) instead of the document-oriented builder-foundation framework.

Relationship to tutorial-builder

This skill extends tutorial-builder. It inherits ALL conventions from skills/builders/tutorial-builder/SKILL.md:

• Workspace structure (SDK-based / Hardhat/Foundry / Hybrid)
• Agent assignments, process phases, milestone template
• GAPS.md convention, GUIDE.md living walkthrough
• Testing philosophy, writing rules, TypeScript conventions
• Hedera/Hiero project conventions (network modularity, SDK pinning, ECDSA keys, state file pattern)

Do NOT duplicate content from tutorial-builder here. This file contains ONLY HIP-specific additions and overrides.

When To Use

• User provides a HIP number, HIP URL, or HIP title and wants a tutorial/demo
• User wants to showcase a new Hedera protocol feature as a code demo
• User needs a demo repo to accompany documentation or a conference talk

Standard Workflow

HIP Research (4 parallel) → North Star + Milestones → Milestone 1 → Verify → ... → Docs → hedera-docs submission

---

Phase 1 Override: HIP Research (Always Run First)

The generic tutorial-builder Phase 1 uses general research agents. For HIP tutorials, replace it with four specialized parallel [RESEARCH] agents launched simultaneously in a single message:

Before launching agents: Extract every URL, repo, issue, PR, spec, and reference from the user's initial message. These go into the North Star's Source Materials table.

[RESEARCH] Agent 1 - HIP Specification:

• Fetch the full HIP text
• Extract: feature description, transaction types, protobuf definitions, Solidity interfaces, status, code examples
• Identify capabilities vs. limitations

[RESEARCH] Agent 2 - SDK Support:

• Search hiero-sdk-js for HIP-related classes
• Find minimum SDK version (CHANGELOG.md, releases, PRs)
• Determine npm vs. GitHub-only availability
• List all SDK classes, methods, and transaction types introduced
• Find example scripts in the repo

[RESEARCH] Agent 3 - Mirror Node API:

• Find all mirror node REST endpoints for the HIP feature
• Document request/response schemas
• Check endpoint availability on previewnet/testnet
• Note the mirror node version with the feature

[RESEARCH] Agent 4 - Existing Docs and Issues:

• Check hedera-docs for open PRs/issues related to this HIP
• Find existing documentation, blog posts, or examples
• Identify gaps the tutorial must fill

After all complete, synthesize and present to user: feature capabilities, SDK status, mirror node availability, key risks.

---

Phase 2 Addition: HIP-Specific North Star Sections

In addition to the standard North Star sections from tutorial-builder, HIP tutorials add:

• Source Materials: Table of every reference (HIP URL, SDK repo, mirror node spec, docs PRs/issues)
• Core Positioning: This HIP vs. alternatives (smart contracts, custom fees, EIP equivalents)
• Key Data Points: SDK version, transaction fees, gas limits, network constraints, mirror node endpoints - all with sources and dates
• Architecture recommendation: SDK-based, Hardhat/Foundry, or Hybrid - justified by Phase 1 research

---

Agent Parallelization Rules (HIP-Specific)

• Phase 1: Always launch all 4 [RESEARCH] agents simultaneously
• Phase 3 contracts: [SOLIDITY] for writing, then [BLOCKCHAIN_SECURITY] immediately for review (separate agents - adversarial auditing requires a different mindset from authoring)
• Phase 3 mirror node: [API_TESTING] on mirror node scripts in parallel with [CODE_REVIEW] on TypeScript scripts
• Phase 5 docs: [ARCHITECTURE] (HOW_IT_WORKS.md) and [WRITING] (PREREQUISITES.md + GUIDE.md) in parallel
• Phase 5 review: [CODE_REVIEW] and [RESEARCH] in parallel for accuracy + fact verification
• Never parallelize: Milestone implementation steps - each verified before the next starts

---

Mirror Node Integration Pattern

Every HIP tutorial must include at least one mirror node query script. Use the mirror node URL from config.ts (single source of truth):

import { getNetworkConfig } from "./utils/config.js";

const { mirrorNodeUrl } = getNetworkConfig();

async function queryFeature(accountId: string): Promise<unknown> {
  const url = `${mirrorNodeUrl}/api/v1/accounts/${accountId}/<feature-endpoint>`;
  console.log(`Querying: ${url}`);
  const res = await fetch(url);
  const data = await res.json();
  console.log(JSON.stringify(data, null, 2));
  return data;
}

---

HIP-Specific Writing Rules

In addition to tutorial-builder's 13 writing rules:

1. Always show the mirror node URL being queried - readers should be able to paste it in their browser
2. Print transaction IDs after every transaction - link to https://hashscan.io/<network>/transaction/<txId>
3. Show HBAR costs for significant transactions (creation, deployment)
4. Note testnet vs. previewnet differences inline when they exist

---

HIP-Specific BACKGROUND.md Content

For HIP tutorials, BACKGROUND.md must include:

• What problem does this HIP solve? (1-2 paragraphs)
• Key concepts a reader needs before running any code
• How does this compare to alternatives (EIP equivalents, smart contracts, custom fees)?
• Links to official HIP spec, SDK docs, and related HIPs
• Known limitations and production considerations

---

hedera-docs Submission

After all milestones complete, create Mintlify MDX tutorial files directly in the hedera-docs repo (not a separate markdown file):

File location: hedera/tutorials/<category>/<tutorial-name>.mdx (e.g., hedera/tutorials/hooks/hello-hooks.mdx)

Structure: Follow existing tutorials (e.g., hedera/tutorials/smart-contracts/hss-x-evm-part-1-*) exactly:

• Frontmatter with title
• Opening paragraph explaining the problem
• <Note> linking to the public demo repository
• Prerequisites section
• Table of Contents with anchor links
• Numbered steps with code blocks (language + filename: ````typescript src/hello-hooks/01-deploy.ts```)
• Conclusion with key takeaways
• <Card> linking to Part 2 (if multi-part)
• Additional Resources with consistent naming
• Writer <Card> at the bottom

Multi-demo tutorials: Split into Part 1 / Part 2 files. Each part is standalone but references the other.

Key rules:

• Reference SDK from npm (@hiero-ledger/[email protected]), not vendor tarballs
• Use relative links for internal docs pages (/hedera/core-concepts/...), not full docs.hedera.com URLs
• Use Mintlify components: <Note>, <Warning>, <Info>, <Accordion>, <Card>, <Columns>, <CodeGroup>
• Include ALL utility files used by the scripts (config, client, state, cost, crypto)
• Use real testnet values in expected output (from a verified run), not placeholders
• Name the project directory to match the public GitHub repo name
• Do NOT include gaps, workarounds, or known limitations - state behavior factually
• Update docs.json navigation to add the new tutorial group

Agent assignments:

• [ADVOCACY] writes the tutorial narrative
• [CODE_REVIEW] verifies every code block matches the demo repo
• [RESEARCH] verifies all data points (SDK version, fees, endpoints) are current

---

Learnings Feedback Loop

After each HIP tutorial is complete and verified, apply non-obvious learnings back:

What to capture:

• New SDK patterns, transaction types, or API quirks
• Agent assignment changes (roles that worked poorly)
• Milestone patterns that worked better than the template
• Network-specific gotchas (previewnet vs testnet)

Where to apply:

• Generic patterns → tutorial-builder
• HIP-specific patterns → hip-tutorial-builder (this file)
• North Star improvements → north-star-builder
• Roster changes → CLAUDE.md Agent Capability Roster

What NOT to capture: Project-specific logic, one-off debugging solutions, SDK version numbers (go in Key Data Points with dates).