Stats
Actions
Tags
From idea-forge
End-to-end skill for creating, reviewing, and updating Hedera/Hiero Improvement Proposals (HIPs). Produces HIP documents in the official format with correct frontmatter, required sections, protobuf definitions, Solidity interfaces, and cross-references to existing HIPs. Includes factual review against official sources (hiero-ledger repo, Hedera docs) and cross-agent review for technical accuracy.
How this skill is triggered — by the user, by Claude, or both
Slash command
/idea-forge:hip-builderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Foundation:** This skill inherits the quality framework from `skills/builders/builder-foundation/SKILL.md`. All Mid-Draft Quality Checks, Quality Dimensions, and Review Tiers defined there apply here. Below are HIP-specific quality prompts and verification procedures.
Foundation: This skill inherits the quality framework from
skills/builders/builder-foundation/SKILL.md. All Mid-Draft Quality Checks, Quality Dimensions, and Review Tiers defined there apply here. Below are HIP-specific quality prompts and verification procedures.
Create, review, or update a Hedera/Hiero Improvement Proposal (HIP) following the official format from the hiero-ledger/hiero-improvement-proposals repository. Output is a versioned Markdown file (or pair: proposal + extended reference) that can be submitted to the Hiero governance process.
This skill handles three modes:
Single document (standard): HIP-XXXX-<Short-Title>.md
Dual document (for complex proposals):
HIP-XXXX-<Short-Title>-Proposal.md (submission artifact, concise)HIP-XXXX-<Short-Title>-Extended-Reference.md (full implementation detail for discussion)Where XXXX is the HIP number (use XXXX for drafts until a number is assigned).
The HIP frontmatter template, the frontmatter field-rules table, and the full HIP
document template (Abstract -> Copyright, including the Solidity Interfaces, Protobuf
Definitions, and System Contract Addresses blocks) live in
skills/builders/hip-builder/hip-templates-and-pitfalls.md. Copy from there when
drafting; do not hand-author frontmatter from memory.
When reviewing a HIP (mode: review), follow this systematic process:
Download the actual source text of every HIP referenced in the proposal:
# Download HIP source from hiero-ledger repo
gh api repos/hiero-ledger/hiero-improvement-proposals/contents/HIP/hip-<N>.md \
--jq '.content' | base64 -d > workspace/<project>/hip-<N>.md
Also search Hedera docs using the MCP tool (mcp__claude_ai_Hedera_Docs__search_hedera) for:
For each factual claim in the proposal, verify against the source:
| Claim Category | What to Check | Common Errors |
|---|---|---|
| Function names | Exact spelling, parameter names, return types | "Sender" vs "Payer", wrong parameter order |
| System contract addresses | Correct hex address | Address assigned to wrong service |
| Transaction types | Actual HAPI transaction body names | Inventing transaction types that don't exist |
| HIP attributions | Which HIP defines which feature | Attributing features to the wrong HIP |
| Behavioral claims | How the protocol actually works | Describing intended behavior, not actual |
| Uniqueness claims | Whether competitors exist | Claiming "first" when others exist |
| Terminology | Official term used in source HIP | Using unofficial terms (e.g., "lambda storage" vs "hook storage") |
For every use case, user story, and motivation claim:
CustomRoyaltyFee, CustomFixedFee, CustomFractionalFee, KYC key, freeze key, pause key, wipe key, fee schedule key, supply key. Does HTS already solve this natively?Output a REVIEW-FINDINGS.md organized by severity:
# HIP-XXXX - Factual Review Findings
**Reviewed against:** <list of sources>
## CRITICAL Issues (Must Fix)
<Issues that make claims factually wrong>
<Includes: wrong function names, triggers mechanism cannot detect, use cases fully redundant with native features>
## IMPORTANT Issues (Should Fix)
<Issues that are misleading or incomplete>
<Includes: missing HTS acknowledgments, unsubstantiated economic claims, hidden limitations>
## MINOR Issues (Nice to Fix)
<Formatting, style, terminology consistency>
## Verified Correct Claims
<Claims confirmed against sources - builds confidence>
For each issue, apply the fix directly to the document(s) and note what was changed.
12 recurring factual errors found in real HIP drafts - wrong function names ("Sender"
vs "Payer"), non-existent transaction types (no HookCreate), HIP attribution
mistakes (HIP-755 vs HIP-1215), uniqueness over-claims, terminology slips ("hook
storage" not "lambda storage"), interface-name precision, return-value handling,
recursion / EVM-frame limitations, and msg.sender-in-hook context. Check every one
during review; full catalog with examples and correct/wrong code in
skills/builders/hip-builder/hip-templates-and-pitfalls.md.
CRITICAL: Every use case and motivation claim in the HIP must be validated against Hedera's actual capabilities. A HIP that proposes solutions for problems Hedera already solves natively, or claims capabilities that the mechanism cannot deliver, will lose credibility with reviewers.
For EVERY use case in the Motivation, User Stories, and Use Case Deep Dives sections, ask and answer these questions:
Hedera Token Service provides protocol-enforced features that many other chains lack. Before proposing a hook/mechanism for a token-related use case, check:
| HTS Feature | What It Does | HIP Must Acknowledge |
|---|---|---|
CustomRoyaltyFee | Protocol-enforced royalty collection on NFT transfers (up to 10 custom fees per token) | Any NFT royalty use case must note HTS already handles basic royalties |
CustomFixedFee / CustomFractionalFee | Protocol-enforced fixed or fractional fees on token transfers | Any token fee use case must note HTS handles static fees |
| KYC key | Binary per-account token authorization (grant/revoke) | Any compliance use case must acknowledge this as an existing primitive |
| Freeze key | Freeze specific accounts for a token | Compliance use cases must acknowledge HTS freeze capability |
| Pause key | Pause all operations for a token | Compliance use cases must acknowledge HTS pause capability |
| Wipe key | Remove tokens from an account | Must acknowledge if discussing token clawback |
| Fee schedule key | Update custom fees | Must acknowledge if discussing fee changes |
| Supply key | Mint/burn tokens | Must acknowledge if discussing supply management |
Rule: If HTS already solves the basic use case, the HIP must explicitly say so and explain what the proposed mechanism adds on top of the native capability. E.g., "HTS provides static KYC/freeze controls. Hooks add programmable, conditional compliance logic."
The most common error: claiming a mechanism responds to something it cannot observe.
| Trigger Claimed | Can Hooks Detect? | Correct Framing |
|---|---|---|
| "When collateral values drop" (price change) | NO - hooks fire on balance changes, not price changes | "When collateral deposits or withdrawals change balances" + note that price-only drops require an oracle push |
| "When reward tokens arrive" (deposit) | YES - this is a balance change | Correct as-is |
| "When an NFT changes hands" (transfer) | YES - this is an ownership change | Correct, but check if HTS royalty fees already handle the use case |
| "When market conditions change" (external data) | NO - hooks only see on-chain state | "When on-chain balances shift" + note external data requires oracle updates |
| "When gas prices spike" (network condition) | NO - hooks fire on entity state changes | Not a valid hook trigger |
Rule: Every trigger description must be an on-chain state change that the mechanism can actually observe. If the use case also needs external data, state the limitation honestly and describe the complementary mechanism (oracle pushes, HIP-1215 periodic checks).
| Claim Pattern | Problem | Fix |
|---|---|---|
| "Guaranteed liquidation" | Hooks cannot guarantee price-driven liquidation (price drops may not cause balance changes) | "Guaranteed collateralization check on every balance change" |
| "Eliminates all keeper costs" | Some use cases still need oracles or off-chain data | "Eliminates keeper costs for event-driven triggers; price-based triggers still need oracles" |
| "$X saved annually" without basis | Unsubstantiated economic claims weaken the proposal | Provide calculation basis or use ranges with stated assumptions |
| "First to offer X" | May be factually wrong | Research exhaustively; use "first major L1 to offer X as native feature" with caveats |
Some use cases that are valid on Ethereum/Solana are unnecessary on Hedera because Hedera has native features those chains lack:
CustomRoyaltyFee is protocol-enforced).Rule: Always research Hedera's native capabilities for every use case. Frame the value-add relative to what Hedera already provides, not what other chains lack.
When reviewing or writing Use Case sections:
| Dimension | What to Look For |
|---|---|
| Depth | Do specifications include complete function signatures and protobuf definitions, or just sketches? Do security implications address specific attack vectors for this mechanism? |
| Originality | Does the rationale acknowledge existing HIPs it builds on vs. departs from? Are rejected ideas genuinely alternative approaches with real trade-offs? |
| Coherence | Does the motivation logically lead to the proposed specification? Are Solidity examples consistent with protobuf definitions? Do use cases match what the mechanism can actually detect? |
| Completeness | Are all use cases validated against Hedera-native capabilities (HTS fees, KYC/freeze/pause/wipe)? Are trigger limitations honestly stated? |
Document evaluator recommended for HIPs. See builder-foundation for invocation pattern.
Review the following Hedera Improvement Proposal for technical accuracy and logical consistency.
Verify:
1. All referenced HIP numbers are correct and the attributions are accurate
2. Function signatures match the actual Solidity interfaces
3. Protobuf definitions are syntactically correct and follow Hedera conventions
4. System contract addresses are correct
5. Security analysis covers all realistic attack vectors
6. The proposal correctly describes how existing HIPs work (no mischaracterizations)
7. Backwards compatibility claims are accurate
8. The specification is detailed enough to implement
9. Rejected ideas are genuinely inferior to the proposed approach
10. Open issues are real unresolved questions (not solved by the spec)
11. Economic arguments are sound - the cost-benefit analysis holds
12. Use cases are realistic and cannot be solved by existing HIPs alone
13. Use cases make sense in Hedera's specific context (HTS native features like CustomRoyaltyFee, KYC/freeze/pause/wipe keys are acknowledged where relevant)
14. Trigger conditions in use cases match what the mechanism can actually detect (on-chain state changes vs external data like price feeds)
15. No use case is redundant given Hedera's native capabilities (e.g., NFT royalties via HTS CustomRoyaltyFee)
Output format:
1) FACTUAL_ERRORS (wrong function names, wrong addresses, wrong HIP attributions)
2) TECHNICAL_GAPS (missing spec detail, incomplete security analysis)
3) LOGICAL_ISSUES (arguments that don't hold, use cases solvable without this HIP)
4) HEDERA_CONTEXT_ISSUES (use cases redundant with HTS native features, trigger conditions the mechanism cannot detect, claims that ignore Hedera-specific capabilities)
5) ECONOMIC_CONCERNS (cost-benefit doesn't add up, value proposition unclear)
6) READY_FOR_SUBMISSION (yes/no + reason)
Review the following Hedera Improvement Proposal for architecture quality and proposal structure.
Verify:
1. Abstract is self-contained and clearly communicates the proposal
2. Motivation establishes genuine need (not manufactured urgency)
3. Rationale clearly explains design decisions and departures from existing HIPs
4. Specification is complete enough to implement without ambiguity
5. Code examples compile and handle return values correctly
6. Security section addresses all realistic attack vectors
7. Rejected ideas are well-reasoned (not strawmen)
8. Open issues are genuine (not already solved by the spec)
9. References are correctly attributed (right functions to right HIPs)
10. The proposal reuses existing infrastructure appropriately
11. The document reads as a coherent technical argument
12. Use cases honestly describe what the mechanism can and cannot do (limitations stated, not hidden)
13. Every trigger condition is something the mechanism can actually detect on-chain
14. Native Hedera capabilities (HTS fees, KYC/freeze/pause/wipe keys, etc.) are acknowledged where they overlap with use cases
Output format:
1) STRUCTURAL_ISSUES (missing sections, wrong section order, incomplete spec)
2) CLARITY_ISSUES (ambiguous language, unclear specification)
3) CODE_ISSUES (examples that won't compile, missing return value handling)
4) DESIGN_CONCERNS (architectural decisions that may cause problems)
5) HEDERA_CONTEXT_ISSUES (use cases that ignore Hedera's native capabilities, triggers the mechanism cannot detect, misleading value propositions)
6) READY_FOR_SUBMISSION (yes/no + reason)
hiero-ledger/hiero-improvement-proposalsTechnical precision over narrative flair. HIPs are read by protocol engineers. Every claim must be verifiable. No marketing language.
Cite your sources. When referencing another HIP's behavior, quote or paraphrase the specific section. Don't rely on memory or summaries.
Function signatures must be exact. Copy from source if possible. Include parameter types, names, and return types.
Explain departures explicitly. If your HIP departs from an existing HIP's design, state: (a) what the existing HIP does, (b) what you propose instead, (c) why the departure is necessary.
Security analysis must be adversarial. Think like an attacker. For each mechanism, ask: "How could someone abuse this?" Address gas exhaustion, griefing, impersonation, front-running, and reentrancy at minimum.
Rejected ideas must be genuine alternatives. Don't create strawmen. Each rejected idea should be a plausible approach that was discarded for a specific, technical reason.
Open issues must be real. Don't list solved problems as open issues. Each open issue should require community input or a design decision that the author cannot make alone.
Example code must compile. Handle return values, use correct interface names, import correctly. Readers will try to use your examples.
Use the official terminology. Check the source HIP for the exact terms it uses. Don't invent synonyms (e.g., "hook storage" not "lambda storage").
Quantify economic claims. "This saves money" is not sufficient. "This replaces $200-500/month in keeper infrastructure costs with ~$50/month in gas budget top-ups" is.
Address the "why not HIP-1215 alone?" question. For any HIP that builds on scheduling, explicitly explain what event-driven capability it adds that time-based scheduling cannot provide.
Every use case must be validated against Hedera's native capabilities. Before claiming a use case, search Hedera docs for native features that may already solve it (HTS fees, KYC/freeze/pause/wipe keys, etc.). If the native feature exists, either remove the use case or explicitly acknowledge what Hedera already provides and explain what the HIP adds on top.
Triggers must be observable on-chain. Never claim a mechanism reacts to external data (prices, market conditions) unless an oracle pushes that data on-chain as a state change. State the limitation honestly.
Use hyphens (-) or semicolons (;) instead of em-dashes in all generated content.
Never use \n or <br/> in Mermaid diagram labels. Keep all node labels on a single line.
HIP URL format is consistent. Always use https://hips.hedera.com/hip/hip-<N> (lowercase, no .html).
Only keep the latest version. Delete previous when new is created.
Before submission, verify items in priority order per builder-foundation tiers.
Version: 3.1.0
Changelog:
skills/builders/hip-builder/hip-templates-and-pitfalls.md. SKILL.md keeps the create / review / update process, use-case fact-checking, writing rules, and review checklist, with pointers to the reference. No behavior change.npx claudepluginhub kpachhai/idea-forge --plugin idea-forgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.