An open protocol for creating interchangeable software pieces,
understandable and resilient over time.
Programs that should do one thing, do a hundred.
Systems that should last decades break in months.
Tools that should be accessible require years to learn.
Solutions that should be universal only work in specific places.
"Every project reinvents the wheel. Login, QR, analytics, validations...
over and over again, with the same mistakes."
Solves a concrete problem that people have today
Few parts, low complexity, easy to understand
Does one thing completely without extras
Resilient to changes, works years later
(USEE Text Format)
"One piece = One problem solved. Documented, tested, ready to use."
./extract-data | ./temporal-analytics | ./generate-report
"Build complex solutions by connecting simple pieces.
No extra code, no configuration, no headaches."
The protocol is not a thought experiment: three independent projects already run on it. Here is what they learned.
All the business logic — allocating overhead, summarising sales by period, normalising ledger entries — lives outside the framework, in pieces the front end calls over HTTP.
What they learned: the pieces run inside serverless functions, and the bundler does not detect them because their paths are resolved at runtime. You have to declare them explicitly in the deployment, and resolve paths relative to the module, never to the working directory.
Guest counts, table capacity, budget and vendor calculations. Each piece was written separately, with no coordination on implementations — only on the input and output format.
What they learned: one shared test runner for every piece, green before you push, is what keeps parallel work from colliding. That runner is published below.
A catalogue where third parties publish their pieces. Accepting a piece without reviewing it by hand meant turning the specification into executable checks.
What they learned: whatever part of a protocol cannot be checked automatically ends up ignored. That is where the Level 1 verifier now documented in the came from.
All three integrations converged on the same exit-code convention. If your piece honours it, exposing it over HTTP is a direct translation, with no business logic in between.
| Exit code | Means | Where the answer goes | HTTP equivalent |
|---|---|---|---|
0 |
All good | stdout, starts with estado: ok |
200 |
2 |
Invalid input | stderr, starts with estado: error |
400 / 422 |
1 |
Internal error in the piece | stderr, starts with estado: error |
500 |
Also: --ayuda and --version always exit
0 and write to stdout. Empty input is
invalid input, so it exits 2.
Learn to run and connect USEE pieces in minutes
Everything you need to know to use USEE pieces: UTF format, basic execution, pipe connections, JSON/HTTP adapters, and complete practical examples.
Ready-to-use tools and examples
Pipeline connecting analytics-temporal → generar-qr
Utility to transform UTF fields between pieces
Tools those projects were already using, published here so you don't write them again. None of them is required: the protocol is the documents.
conformance runner · Node, no dependencies
Drop this file next to your pieces and run it. It checks the
required structure, the 10 manifest sections, that the LEEME
documents what the piece does not do, the CLI contract,
that ENTRADA.ejemplo literally produces
SALIDA.ejemplo, and every case in
pruebas/. It exits 1 on any failure, so it works as-is
in CI.
node probar # every piece in the folder
node probar calcular-saldo # just oneclonable scaffold
A complete piece, already green. As it stands, it numbers and counts the items it receives: enough to confirm the whole cycle works before you write anything of your own. Clone it, rename it with a verb + noun, and replace the manifest fields.
skill for coding agents
The protocol condensed into one file an AI can follow. Put it at
.claude/skills/usee-pieza/SKILL.md in your repository
and stop explaining the protocol on every request. Outside that
environment it works just as well as a prompt. Written in Spanish,
like the protocol's own vocabulary.
migration for existing manifests
Brings the PIEZA.usee files you already have in line
with the current categoria and
modelo_cobro rules. Dry run by default: it writes
nothing until you ask with --aplicar.
Full detail for each resource in the .
Explore real USEE pieces to understand the protocol structure
Generates customizable QR codes from text
Processes visit data in temporal periods with aggregations
Copy the context below and paste it into any AI (Claude, ChatGPT, Gemini…). It gives everything needed to design and write a correct USEE piece from scratch.
You are an expert assistant in the USEE protocol. Your task is to help me create a correct USEE piece according to the protocol standard.
## What a USEE piece is
A USEE piece is an atomic program (a CLI) that does ONE single thing: it reads from stdin and writes to stdout using FTU (USEE Text Format, plain text). Errors go to stderr. A piece name is always "verb + noun" (e.g. generate-order-number, calculate-stock, convert-unit).
## The 4 principles (must always hold)
- Useful: solves a concrete problem someone has today.
- Simple: few pieces, low complexity, easy to understand.
- Essential: does one complete thing, no extras or "convenience" features.
- Stable: backward-compatible inputs and outputs. A breaking change = a NEW piece with a new name, never break the existing one.
## Mandatory folder structure (pieces/<name>/)
PIEZA.usee ← manifest in FTU
ejecutar ← executable entry point (reads stdin, writes stdout)
ENTRADA.ejemplo ← example input in FTU
SALIDA.ejemplo ← example output in FTU (must be produced literally by ./ejecutar < ENTRADA.ejemplo)
LEEME.md ← human documentation; must explicitly state what the piece does NOT do
pruebas/ ← cases: <name>.entrada + <name>.salida (or .codigo for expected errors)
Inside a .salida, the line "clave: *" accepts any value for that key.
That is how non-deterministic fields (timestamps, identifiers) stay
testable instead of going untested.
## FTU format
- "key: value" syntax, one pair per line.
- Comments with #.
- Multi-line blocks with | and 2-space indentation.
- Repeated keys (e.g. linea:, orden:) represent lists/arrays.
- UTF-8 encoding.
## PIEZA.usee manifest (sections, in this order)
Section headers and keys are literal and in Spanish — Spanish is the protocol's own vocabulary. Write them exactly as shown; do not translate them.
1. # Identidad — nombre, version, creador, fecha_creacion
2. # Descripción — descripcion_corta, descripcion_larga (| block)
3. # Clasificación — categoria, etiquetas
categoria: one of autenticacion, almacenamiento, comunicacion, datos, documentos, imagenes, integracion, pagos, reportes, seguridad, utilidades, otro. If none fits, use the open prefix "dominio:<slug>" (lowercase, digits and hyphens; e.g. dominio:inventario). Never invent a bare category with no prefix.
4. # Capacidad — accion, entrada_descripcion, salida_descripcion
5. # Requisitos — lenguaje, version_lenguaje_minima, dependencias_externas, dependencias_usee
6. # Comercial — costo_por_uso, moneda, modelo_cobro
modelo_cobro: por_llamada | por_minuto | por_registro | gratuito. If the piece does not charge, use gratuito with costo_por_uso: 0.
7. # Configuración — opciones_configuracion, configuracion_requerida
8. # Rendimiento — tiempo_respuesta_promedio_ms, memoria_maxima_mb
9. # Compatibilidad — sistemas_operativos, requiere_red, requiere_almacenamiento
10. # Metadatos adicionales — protocolo_usee, licencia
## Contract of the "ejecutar" executable
- Supports --ayuda/-h and --version/-v.
- If it receives no stdin input (TTY) → error with exit code 2.
- Parses FTU from stdin, validates every field, and on error emits to stderr: estado: error / codigo / mensaje / sugerencia.
- OK output to stdout: estado: ok / <result fields>.
- Exit codes: 0 = ok, 2 = input/validation error, 1 = general/fatal error. When exposing it over HTTP, the convention observed in production is 0 → 200, 2 → 400/422, 1 → 500.
- Optional configuration via environment variables prefixed USEE_<NAME>_<OPTION>. Never mandatory configuration for the common case.
- No external dependencies if possible. For money, use fixed decimals (2), never raw floats.
- The piece does NOT access a database or the network unless its action explicitly requires it: it receives everything through the input so the consumer decides the source.
- Deterministic and composable: it must chain with other pieces (pieceA | pieceB | pieceC).
- Self-contained: the FTU parser and serializer go inline inside "ejecutar". No shared library across pieces, even at the cost of repeated code: the folder has to be clonable and movable on its own. This is the rule most often broken and the most expensive one to break.
- If your piece consumes another piece's output, declare that relationship in dependencias_usee in the manifest, not as a code dependency.
- Any path to the piece's own files resolves relative to the module, never to the working directory: anything that depends on the cwd breaks once it is bundled into a serverless environment.
## Checklist before considering it done
- The purpose fits in "verb + noun".
- PIEZA.usee has all required fields and is valid FTU.
- "ejecutar" reads from stdin and writes FTU to stdout; errors go to stderr.
- ENTRADA.ejemplo produces SALIDA.ejemplo literally.
- LEEME.md documents what the piece does NOT do.
- No unjustified external dependencies; no mandatory configuration.
- categoria and modelo_cobro use valid values (see above); the verifier rejects anything else.
- The piece passes the full "probar" verifier, all green.
## What I need from you
1. Ask me what the piece should do if I haven't said so.
2. Propose a "verb + noun" name and check it is atomic (one single thing).
3. Generate the complete files: PIEZA.usee, ejecutar, ENTRADA.ejemplo, SALIDA.ejemplo, LEEME.md and at least one case in pruebas/.
4. Show the command to test it locally and verify that ENTRADA.ejemplo produces SALIDA.ejemplo.
5. Validate it with the official verifier before calling it done: download https://www.usee.family/recursos/probar and run "node probar <piece-name>". It is not finished until everything passes green.
If you would rather start from a scaffold that is already valid instead of writing the files from scratch, clone https://www.usee.family/recursos/plantilla-pieza/ and replace the fields marked TODO: it brings the full structure with its tests already passing.Want the full protocol detail? Check the Manifesto and documentation before publishing your piece.