---
name: kiloscribe-inscriptions
description: Inscribe user-approved files and URLs on Hedera through KiloScribe, verify the result, and return durable HCS references.
version: 1
---

# KiloScribe inscriptions

Use this skill when a user wants to publish a file, URL, Hashinal, NFT
metadata, HTML experience, or other durable artifact on Hedera.

## Choose the protocol

- **HCS-1**: immutable file content. Use for media, HTML, JSON, and public
  artifacts that should not change.
- **HCS-5**: Hashinal metadata attached to a file or NFT workflow. Keep the
  creator, name, description, type, and attributes explicit.
- **HCS-3**: a portable reference that lets another application resolve
  Hedera-backed content. Use it when the user is connecting published content
  into a larger experience.

Do not substitute a vague product label for the protocol name. HCS-1, HCS-5,
and HCS-3 have different jobs.

## Required inputs

Collect only what is needed:

1. source URL or local file path;
2. target standard and network (mainnet is the default, testnet must be
   explicit);
3. creator, name, description, MIME type, and optional tags/attributes;
4. payment route: a user-connected Hedera wallet, existing KiloScribe credits,
   or a direct delegated signer in a server runtime.

If the user has not approved a paid action, stop after the quote. A credit
purchase can be completed in the KiloScribe workspace with Stripe or a Base EVM
wallet. Once credits are available, select **Credits** in the inscription
workspace; the status page reports the broker job until the topic is ready.

## Preferred workflow

1. Inspect the artifact and reject missing or ambiguous inputs.
2. Select HCS-1/HCS-5/HCS-3 and explain why in one sentence.
3. Generate a quote with `generateQuote` from
   `@hashgraphonline/standards-sdk`.
4. Show the message-tier estimate, topic charge, total, and quote expiry.
5. Request explicit confirmation immediately before execution.
6. Execute with [`inscriber.ts`](./inscriber.ts), a user wallet, or the
   KiloScribe credit workspace.
7. Poll until the job is confirmed; retry reads, never paid writes.
8. Verify the public CDN result and return the IDs and references.

## Server signer rules

The starter uses the standards SDK's Node signer path. Set credentials only in
the process environment:

```bash
KILOSCRIBE_ACCOUNT_ID=0.0.xxxxx
KILOSCRIBE_PRIVATE_KEY='your-server-only-key'
KILOSCRIBE_NETWORK=mainnet
```

Never put a private key in a prompt, tool argument, log, issue, or generated
file. Use a least-privileged, dedicated account and a spending limit. Prefer a
quote-only dry run for new inputs.

## Verification checklist

- `confirmed` is true, or a final retrieval reports `completed: true`.
- The returned topic ID is present and is not inferred from user text.
- The public CDN URL responds with the expected content type.
- HCS headers/reference metadata identify the selected standard.
- The final response distinguishes quote, submitted, processing, and complete.

## Canonical files

- Prompt: `https://kiloscribe.com/ai/prompt.md`
- SDK starter: `https://kiloscribe.com/ai/inscriber.ts`
- Machine-readable manifest: `https://kiloscribe.com/ai/manifest.json`
- Human docs: `https://kiloscribe.com/docs`