Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

pubba

/pubba

Konfiguruje silnik grafu wiedzy pubba dla stron portfolio, mapuje treści na encje i generuje znaczniki schema.org oraz llms.txt.

Repozytorium
pubba ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/pubba.sh

Co robi i kiedy

Konfiguruje silnik grafu wiedzy pubba dla stron portfolio, mapuje treści na encje i generuje znaczniki schema.org oraz llms.txt.

Wyzwalacze z opisu

showroom
Oryginalny opis (EN)

Set up and maintain pubba, a knowledge-graph engine for portfolio and "showroom" sites (related items with reasons, what-next from a visitor's trail, typo-tolerant matching). Use when someone wants to add pubba to a site, map their content (JSON, Markdown, a CMS export, a database dump) to pubba's entities and links, generate schema.org JSON-LD or an llms.txt from it, or run and improve pubba's evaluation harness (aliases, weights, rules).

Jak działa

  1. 1. Map the site's content to the schema
  2. 2. Generate JSON-LD and llms.txt
  3. 3. Run the evaluation harness and suggest fixes
  4. 4. Add a guide, in any design
  5. Rules
Sekcje z nagłówków SKILL.md, w oryginale · 170 linii, 1 578 słów
Podgląd SKILL.md
---
name: pubba
description: Set up and maintain pubba, a knowledge-graph engine for portfolio and "showroom" sites (related items with reasons, what-next from a visitor's trail, typo-tolerant matching). Use when someone wants to add pubba to a site, map their content (JSON, Markdown, a CMS export, a database dump) to pubba's entities and links, generate schema.org JSON-LD or an llms.txt from it, or run and improve pubba's evaluation harness (aliases, weights, rules).
---

# pubba

pubba turns a site's content into **entities** and **typed links**, then answers
three things from that graph: what is related to an item and why, what a visitor
is likely to want next from their trail, and what a typed query means. Every
answer carries a machine-readable reason plus a sentence.

Portfolios are the main case and have a preset (`"preset": "portfolio"`). Any
other showroom (a catalogue, a course list, docs) uses `"preset": "none"` and its
own types, link kinds and rules.

Everything here runs through the CLI. Call it with `scripts/pubba.sh` (in this
skill folder): it uses the project's installed `pubba`, else a checkout named by
`PUBBA_HOME`, else `npx pubba`.

| Command | What it does |
| --- | --- |
| `pubba.sh compile <pubba.json> --out <bundle.json>` | The finished graph as one JSON file, which the site's runtime loads (`loadBundle`) |
| `pubba.sh preview <pubba.json>` | The mapping as Markdown tables: entities, links, which links rules derived, and what got dropped |
| `pubba.sh inspect <pubba.json>` | Counts by type and kind |
| `pubba.sh match <pubba.json> "<query>"` | What a query resolves to, and why |
| `pubba.sh related <pubba.json> <id>` | Related items with reasons |
| `pubba.sh next <pubba.json> <id> [<id>…]` | Predictions after a trail |
| `pubba.sh lint <pubba.json>` | Content problems that cost accuracy (name collisions, heavy weights, dead ends); exits 1 on errors |
| `pubba.sh eval <pubba.json> --queries q.json --trails t.json --generated --baseline b.json` | Scores matching and suggestions, with cases generated from the content added; exits 1 on a drop |
| `pubba.sh generate <pubba.json> --out-dir eval/` | Writes the generated cases, to read |
| `pubba.sh jsonld <pubba.json> --base-url <url> [--out file]` | schema.org JSON-LD, validated; exits 1 on problems |
| `pubba.sh llms <pubba.json> --base-url <url> [--out file]` | An llms.txt |

Read `references/schema.md` before writing a `pubba.json`; it has the full format.

## 1. Map the site's content to the schema

1. **Find the content.** Look for the data the site already renders: JSON or YAML
   files, Markdown with front matter, a CMS export, seed files, a database dump.
   Don't ask the user to retype anything the repo already has. Read
   `references/mapping.md` for how each kind of source maps.
2. **Choose the route.**
   - A portfolio (projects, skills, roles, places shipped to, games, creative
     work): write a `PortfolioInput` file and a `pubba.json` with
     `"preset": "portfolio"`. The preset brings the 12 link kinds, weights, rules
     and sentences, and derives same-stack, used-with, made-at, used-at, topics and
     mentions by itself.
   - Anything else: write entities and links directly, with the site's own types,
     kinds and rules in `config` (start from `templates/pubba.custom.json`).
3. **Propose before writing.** Draft the mapping in a scratch file, run
   `pubba.sh preview <draft>` and show the user, in this order:
   - the types and link kinds you chose, and why;
   - aliases you added (short forms, abbreviations, company names, old names);
   - weights: which skills or materials count as "core" (1) and which are common
     tools (0.4), since common ones must never make two items look alike;
   - the derived-link rules and what they produced (the `source` column);
   - anything with no links (never suggested, only found by name), and content
     you left out.

   Ask for changes. **Write `pubba.json` (and the content file) into the project
   only after the user agrees.**
4. Keep ids stable (`project:<slug>`, `tech:<name>`): trails saved in visitors'
   browsers and analytics refer to them.

## 2. Generate JSON-LD and llms.txt

1. Ask for the site's public base URL if it isn't in the content.
2. Run `pubba.sh jsonld pubba.json --base-url <url> --out public/pubba.jsonld`.
   It builds a `Person` (knowsAbout from skills, worksFor from current roles,
   sameAs), `SoftwareApplication` for projects and `CreativeWork` for creative
   pieces, each with `creator` pointing at the person. It validates as it writes
   and exits 1 on a problem (missing names, relative urls, dangling ids).
   - Email is left out unless the user asks; it's personal data.
   - In code, `toJsonLd(graph, { knowsAbout: [...] })` takes a curated skill list,
     and `{ include: ["project:<slug>"] }` gives one project page's subset.
   - If the site already has hand-written JSON-LD, diff the two and point out
     what the generated one adds or loses before replacing anything.
   - To use it in a page, embed it in a `<script type="application/ld+json">`.
     Suggest checking it with the Schema.org validator or Google's Rich Results
     Test; you can't reach those for the user unless a browser tool is available.
3. Run `pubba.sh llms pubba.json --base-url <url> --out public/llms.txt`. It is
   served from the site root as `/llms.txt`.
4. Show both outputs to the user before they ship.

## 3. Run the evaluation harness and suggest fixes

The goal is 100% on generated cases and close to it on hand-written ones, kept
there as the content grows.

1. **Lint first:** `pubba.sh lint pubba.json`. Fix errors (duplicate names) before
   anything else; explain each warning to the user and let them choose.
2. **Build the hand-written set from the site's own content**, starting from
   `templates/queries.example.json` and `templates/trails.example.json`. Cover
   every tag:
   - `typo`: real misspellings of the site's names ("flutr", "sri lankan")
   - `one-word`: a single name, abbreviation or short form
   - `similar`: "anything like X?" (`"intent": "similar"`)
   - `place` and `role`: "what did they build in X?", "what do they do at Y?"
   - `off-topic`: weather, jokes, recipes, passwords; these expect `null` and
     `"intent": "none"`
   - trails: 8 to 12 realistic visits with the 1 to 3 items a person would expect
     next. Write the expectations from what makes sense for a visitor, not from
     what pubba currently outputs.
   Generated cases (`--generated`) already cover every name, a typo of it,
   aliases, "anything like it" and each item's closest relation, so spend the
   hand-written set on what generation can't know: off-topic questions, commands
   the site handles itself, and real visitor phrasing.
3. Run `pubba.sh eval pubba.json --queries eval/queries.json --trails eval/trails.json --generated`.
4. For each failure, find the cause with `pubba.sh match` / `next` / `related`,
   then suggest the smallest fix. See `references/evaluation.md` for the
   catalogue. In short:
   - wrong entity for a query: add an alias, or add a stop word, or move a type to
     an earlier or later match tier;
   - an off-topic query matched something: the near-miss rule caught a common
     word; rename the alias or make the type `phrase` mode;
   - a trail misses an obvious next item: check the link exists (`related`), then
     the kind's `pull`, then whether a common tool's weight is too high and
     floods the results;
   - a sentence reads badly: override its template.
5. Show the fixes as a diff, apply them once the user agrees, and rerun.
6. When the scores are where the user wants them, write the baseline with
   `--baseline eval/baseline.json --update-baseline`, and add the eval command to
   CI with `lint`, so a drop or a name collision fails the build (example in
   `references/evaluation.md`). Every content publish then re-runs it, and the
   generated cases grow with the content.

## 4. Add a guide, in any design

The site owner decides what the guide looks like: a search bar, a chat bubble,
a bot, a character, a sidebar, anything. Ask them; don't pick for them. pubba's
`createGuide` is headless, so any of these sits on the same brain.

1. **Ask** what form they want, where it lives, and how it should sound. Look at
   the site's own components, styles and design tokens before building anything.
2. **Compile** in the build: `pubba.sh compile pubba.json --out <public path>/pubba.bundle.json`
   (or keep `createPubba` with the content at build time, if the site already
   has it in JavaScript).
3. **Wire** it, in the site's framework:
   - `const pubba = loadBundle(bundle, { events })` and
     `const guide = createGuide(pubba, { trail: createTrail({ storage: sessionStorage }), route })`,
     where `route(entity)` returns that entity's url in this site.
   - Record steps: `guide.visited(id)` on every page or item view;
     `guide.follow(id, via)` when the guide's action or a chip took the visitor there.
   - `guide.ask(text)` for typed questions: show `text`, perform `action`
     (navigate), show `chips`. For `kind: "none"`, show the chips (or, if the
     site has an AI, ask it and fall back to the chips on any failure).
   - Nudges: after each step the visitor takes themselves, schedule
     `guide.nudge()` after `guide.nudgePolicy.delayMs`; show it if not null.
   - Words: pass `templates` for the guide's voice and language.
4. **Accessibility:** keyboard reachable, focus handled when it opens and
   closes, announced replies (`aria-live`), labelled controls, and respect
   reduced motion.
5. **Verify** in a browser: ask a name, a typo, "anything like X", an
   off-topic question; follow a chip; check a nudge appears once. Then run lint
   and the evaluation.

**Platforms:** runtimes exist for JavaScript/TypeScript (any web framework,
Node, React Native with an async storage wrapper for the trail, Electron) and
Python (`pip install pubba`: Django, FastAPI, Flask, scripts; same API in
snake_case: `load_bundle`, `create_guide`, `guided_to`). For Kotlin, Swift,
Dart, C# or PHP projects, say plainly that their runtime isn't released yet
(see the library's docs/multiplatform-design.md); offer `pubba serve` (HTTP)
as a bridge, and you can still map the content, compile the bundle and run the
evaluation now. For AI assistants, `pubba mcp <bundle>` serves the site as
read-only MCP tools.

## Rules

- Show the mapping and any change to aliases, weights or rules before writing it.
- Never put message text, visitor questions or anything identifying into the
  graph, the eval files or exports.
- Don't publish, push or deploy anything; generating files locally is the job.
Pliki w paczce (8)
  • SKILL.md 10 KB
  • references/evaluation.md 5 KB
  • references/mapping.md 4 KB
  • references/schema.md 8 KB
  • scripts/pubba.sh 1 KB
  • templates/pubba.custom.json 2 KB
  • templates/queries.example.json 3 KB
  • templates/trails.example.json 2 KB

Wersje

W bazie nie ma innych skilli o nazwie pubba.

Migawka bazy z 13.11.2026 · wersja paczki 5f2d555ecadb (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100jsonld-knowledge-graph
    Projektuje i wdraża graf wiedzy JSON-LD (graph.jsonld) obok llms.txt, kodujący encje i relacje projektu jako trójki schema.org.
  • 90ring:generating-llms-txt
    Generuje lub audytuje plik llms.txt repozytorium zgodnie ze specyfikacją llmstxt.org oraz tworzy brakujące CLAUDE.md i AGENTS.md na podstawie README, plików budowania i dokumentacji.
  • 100llms-txt
    Tworzy lub poprawia plik llms.txt i llms-full.txt dla strony na podstawie jej prawdziwych podstron i dodaje go do kodu.
  • 100mdbook-llms
    Dodaje do książki mdBook pliki llms.txt, llms-full.txt i Markdown dla każdego rozdziału, dla modeli językowych.
  • 84llms-txt
    Tworzy i utrzymuje pliki llms.txt i llms-full.txt, które mówią crawlerom AI, jakie treści na stronie są najważniejsze.
  • 100geo-fix-llmstxt
    Generuje pliki llms.txt i llms-full.txt dla strony internetowej, aby poprawić jej czytelność i wykrywalność przez systemy AI.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.