@eristack/ai-knowledge/docs/authoring.md

Eristack knowledge pack for AI agents: recommend packages first, load the right Intent skills, and keep catalog facts in sync

---
title: Authoring
description: Add recipes and keep skills discoverable
sidebar_position: 5
---

# Authoring

## Recipe checklist

1. Confirm the package is in the catalog (`packages/<category>/<name>/package.json` publishable).
2. Confirm skill ids exist under that package’s `skills/*/SKILL.md`.
3. Add an entry to `knowledge/recipes.yaml` with unique `id`, `priority`, `triggers`, `rationale`, `packages`.
4. Prefer **product language** triggers (what users say), not internal API names alone.
5. `pnpm knowledge:sync` && `pnpm knowledge:check`.

### Priority guidance

| Range | Use |
| --- | --- |
| 1–9 | Broad “build an ERP app” style recipes |
| 10–20 | Core domain capabilities |
| 25–40 | Adapter / wiring recipes (load after core) |

Lower number wins ties after score.

## Skill frontmatter

Package skills need Intent-compatible frontmatter (`name`, `description`, `metadata`, `sources`). Descriptions should be searchable: include the package name, key APIs, and when to load.

Set `metadata.library_version` to the **same** value as that package’s `package.json` `version` before publish. Skills are **not** independently versioned or released — they ship as files inside the npm tarball (`files` includes `skills/`).

After changing skills or public exports agents should see:

```bash
pnpm knowledge:sync
```

Never hand-edit `src/generated/*` or the `<!-- catalog:* -->` block in `skills/recommend-eristack/SKILL.md`.

## Package design targets (hard rule)

Every recipe/skill/docs change should support the four targets in `knowledge/agent-workflow.md` § Design targets:

1. **Cheap (tokens)** — one load path; ≤3 files to integrate
2. **Predictable** — string-first domain values; documented defaults
3. **Reliable** — Drizzle/DB default in guidance; no demo stores as production path
4. **Clear boundaries** — export registries/helpers; consumers must not reinvent parallel lists or coercion logic

See `.cursor/rules/eristack-package-targets.mdc`.

## Token-efficient documentation (hard rule)

**In-depth ≠ many files.** Agents are the primary readers; token budget matters.

| Topic scope | Where facts live |
| --- | --- |
| Cross-package (upgrade, Backseat spine, peers) | **One** `knowledge/<topic>.md` + site `docs/<topic>.md` + one Intent skill with **one** `sources` entry |
| Single package production wiring | That package’s `docs/` + skills |
| Package-only Backseat delta | ≤15-line redirect in `docs/backseat.md` pointing to upgrading §3 |

If your recipe rationale says “see each package’s doc”, rewrite it to name the **single canonical load command** instead.

See `.cursor/rules/docs-depth-tokens.mdc`.

## Releasing `@eristack/ai-knowledge`

One Changeset → one package version bump → one npm publish. That publish includes:

| Artifact | Source |
| --- | --- |
| `recommend()` / `loadPlan()` | `src/` |
| Generated catalog + recipes | `src/generated/` (from `pnpm knowledge:sync`) |
| Intent skills | `skills/*/` |
| Knowledge markdown | `knowledge/` |

You do **not** cut a release per skill. Edit skills in-tree, sync the catalog, add a changeset on this package (patch for guidance/catalog refresh; minor if the recommend API or recipe model changes), merge to `main`, then merge the Version Packages PR.

When sibling packages gain skills/recipes, bump **those** packages as usual **and** bump `@eristack/ai-knowledge` so consumers get the regenerated catalog embedded in this package.

## Publishing the Agensi pack

The same skills are listed free on [Agensi](https://www.agensi.io) as **Eristack AI Knowledge Pack**. Every `@eristack/ai-knowledge` release flows there in three steps:

| Step | Who | What happens |
| --- | --- | --- |
| 1. Release | `release.yml` (automatic) | After npm publish of `@eristack/ai-knowledge`, runs `agensi:release` and attaches `eristack-ai-knowledge-pack.zip` + `submission.json` to the `@eristack/ai-knowledge@<version>` GitHub release. If a check fails, the run shows a warning instead (npm publish is unaffected). |
| 2. Send | Maintainer's agent in Cursor | Ask "publish the Eristack pack to Agensi" → project skill `.cursor/skills/agensi-publish` rebuilds, picks `submit_skill` (first time) or `update_skill`, and shows the preview. |
| 3. Approve | Maintainer | Reply "yes"; Agensi scans and reviews. The live version keeps serving until the update is approved. |

Step 2 cannot run headless in CI: Agensi accepts only OAuth tokens (no API keys), refresh tokens rotate on every use, and a new client on the account signs out every other client — a CI bot would keep disconnecting the maintainer's own agent.

```bash
pnpm --filter @eristack/ai-knowledge agensi:pack      # local preview: folder, zip, submission.json
pnpm --filter @eristack/ai-knowledge agensi:release   # + version on npm + clean changelog (network)
```

Listing fields (summary, description, demo, tags, keywords, use cases, FAQ, `agensi_id`) live in `agensi/listing.yaml`; the build enforces Agensi limits and keeps pricing `free`. The changelog comes from this package's `CHANGELOG.md` section with commit hashes removed; if that text is not public-safe, add `agensi/changelog/<version>.md` instead.

The build copies `skills/`, `knowledge/`, `agensi/README.md` (pack title + generated skill table) and `LICENSE`; renames skills to `eristack-<name>` (`recommend-eristack` → `eristack-recommend`, `upgrading-eristack` → `eristack-upgrading`) because Agensi names are global; and rewrites frontmatter to `name`, `description`, `version`, `docs_url`.

| Left out of the pack | Why |
| --- | --- |
| `dev-conventions` skill + guide | Monorepo contributor rules |
| `tiga-sekawan-3ss-adoption` skill, guide, recipe | Client-specific |

The build **fails** on: more than 50 skills, client names or batch codes, demo passwords or secret-shaped strings, `@eristack/*` names missing from the catalog (except placeholders the guides mark as not shipped), dead `@eristack/<pkg>#<skill>` anchors, and dead relative links. `tests/agensi-pack.test.ts` runs it in CI.

## Tooling prompts

The `ai-toolbox` skill (in this package) carries feature-brief prompts and checklists for money/auth/doc-number. Use it when drafting new recipes or agent runbooks.

## Related

- [Catalog sync](./sync.md)
- [Skills](./skills.md)
- [Recipes](./recipes.md)