pi-simocracy 0.7.0 → 0.8.0

package/README.md

@@ -40,6 +40,7 @@ pi install npm:pi-simocracy
 | `simocracy_lookup_record` | Fetch a sim / proposal / gathering / decision / comment by AT-URI or fuzzy name. Returns the record + comment subtree, with sim-authored comments flagged inline (🐾) so you can tell which opinions are human and which are sim. Use this before `simocracy_post_comment` to find the right `subjectUri`. |
 | `simocracy_post_comment` | Post a comment on a record **as the loaded sim**. Writes the comment plus an `org.simocracy.history` sidecar that attributes it to the sim. Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) for the design. |
 | `simocracy_post_proposal` | Submit a new funding proposal (`org.hypercerts.claim.activity`) **as the loaded sim**. Writes three records to the user's PDS: the proposal itself, an `org.simocracy.proposalContext` sidecar binding it to a parent gathering or FtC SF floor (required for visibility on `/proposals`), and an `org.simocracy.history` sidecar with `type: "proposal"`. You must pass exactly one of `gatheringUri` (an AT-URI to an `org.simocracy.gathering` — use `simocracy_lookup_record` to resolve a name) or `ftcSfFloor` (1–14). Optional itemized `budgetItems`, `workScope` tags, `contributors`, and an https `imageUri` (the default Simocracy banner is used otherwise — image upload from disk is intentionally not supported). Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) for the design. |
+| `simocracy_post_skill` | Publish an Anthropic-style agent skill (`org.simocracy.skill`) **as the loaded sim**. Writes two records to the user's PDS: the skill itself (`name` + `description` + `body` — same shape simocracy.org's SkillFormDialog writes) and an `org.simocracy.history` sidecar with `type: "skill"`. Skills appear at `simocracy.org/skills/<did>/<rkey>` with the full SKILL.md served at `.../skill.md` for loading into any agent harness. Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_SKILLS.md`](docs/SIM_AUTHORED_SKILLS.md) for the design. |
 | `simocracy_update_sim` | Rewrite the loaded sim's constitution (`shortDescription` + `description`) and/or speaking `style` and persist to your PDS. Requires `/sim login` + sim ownership. |
 
 ---
@@ -67,6 +68,13 @@ Pi rewrites the constitution and calls `simocracy_update_sim` to persist it. The
 ```
 Pi calls `simocracy_lookup_record` to find the AT-URI, then `simocracy_post_comment` to write the comment + the attribution sidecar.
 
+**Publish a skill as your sim:**
+```
+/sim my mr meow
+> draft a SKILL.md for evaluating cat-sanctuary proposals and publish it
+```
+Pi writes the SKILL.md (`name`, `description`, `body`) in the sim's voice, then calls `simocracy_post_skill` to publish the `org.simocracy.skill` record + the attribution sidecar. The skill appears on `simocracy.org/skills` and is loadable into any agent harness via `/skills/<did>/<rkey>/skill.md`.
+
 ---
 
 ## Loaded-sim system prompt
@@ -95,6 +103,7 @@ In Kitty / Ghostty / WezTerm / Konsole / iTerm2 the sprite renders as a true-col
 - [`AGENTS.md`](AGENTS.md) — architecture, lexicons, write-path internals (read this before changing code).
 - [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) — how human-vs-sim comment attribution works without changing the impactindexer lexicon.
 - [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) — same pattern, applied to `org.hypercerts.claim.activity` proposals.
+- [`docs/SIM_AUTHORED_SKILLS.md`](docs/SIM_AUTHORED_SKILLS.md) — same pattern, applied to `org.simocracy.skill` agent skills.
 - [Simocracy](https://simocracy.org) · [pi](https://github.com/mariozechner/pi-coding-agent)
 
 MIT — see [LICENSE](LICENSE).

package/docs/SIM_AUTHORED_SKILLS.md

@@ -0,0 +1,221 @@
+# Sim-authored skills
+
+How pi-simocracy attributes an Anthropic-style agent skill
+(`org.simocracy.skill`) to a sim *without* extending the skill
+lexicon — and how
+[simocracy-v2](https://github.com/GainForest/simocracy-v2) renders
+the attribution. Same pattern as
+[sim-authored comments](./SIM_AUTHORED_COMMENTS.md) and
+[sim-authored proposals](./SIM_AUTHORED_PROPOSALS.md), different
+subject collection.
+
+---
+
+## TL;DR
+
+When pi publishes a skill on behalf of a loaded sim, it writes
+**two** records to the user's PDS:
+
+1. **`org.simocracy.skill`** — the skill itself, in the exact shape
+   simocracy.org's `SkillFormDialog` already writes today: `name`
+   (lowercase kebab-case identifier), `description` (the SKILL.md
+   trigger text), `body` (the markdown instructions, no YAML
+   frontmatter), `createdAt`. Old readers (the existing skills
+   gallery, the `/skills/[did]/[rkey]/skill.md` route) see this
+   as a regular user-authored skill — graceful degradation.
+2. **`org.simocracy.history`** — sidecar with `type: "skill"`,
+   `subjectUri` pointing at the skill we just wrote,
+   `subjectCollection: "org.simocracy.skill"`, `simUris[]` /
+   `simNames[]` declaring which sim spoke, and a denormalized
+   `content` snippet (the description) so the timeline renders
+   without a second round-trip.
+
+Renderers that understand the history join (simocracy.org, after
+the planned change lands) display a sim badge on the skill card;
+renderers that don't keep showing it as a regular user skill.
+**Zero skill lexicon changes.**
+
+---
+
+## Why no lexicon change
+
+The `org.simocracy.skill` record schema is intentionally minimal —
+it's just `name` + `description` + `body` so any agent harness can
+load it via the `/skills/[did]/[rkey]/skill.md` reconstruction
+route. Adding a `sim` StrongRef field would couple the skill
+lexicon to a Simocracy-specific concept (sim-authorship) and break
+the "this is just a SKILL.md container" framing.
+
+The `org.simocracy.history` lexicon already has every field we
+need — same case made for comments
+([`SIM_AUTHORED_COMMENTS.md`](./SIM_AUTHORED_COMMENTS.md)) and
+proposals ([`SIM_AUTHORED_PROPOSALS.md`](./SIM_AUTHORED_PROPOSALS.md)),
+applied verbatim:
+
+| Field              | Used for sim-authored skills                                   |
+|--------------------|----------------------------------------------------------------|
+| `type`             | `"skill"` (new value — appended like other event types)        |
+| `actorDid`         | The human who published on the sim's behalf                    |
+| `simNames[]`       | Display name(s) of the sim(s) credited as author               |
+| `simUris[]`        | AT-URI(s) of the sim(s) — the sim-attribution key              |
+| `subjectUri`       | AT-URI of the skill record this attribution applies to         |
+| `subjectCollection`| `"org.simocracy.skill"`                                        |
+| `subjectName`      | Skill name (denormalized for the timeline)                     |
+| `content`          | Skill description (denormalized so the indexer doesn't have to fetch the skill record to render the timeline) |
+| `createdAt`        | ISO timestamp                                                  |
+
+Use it as-is.
+
+---
+
+## Write path (pi-simocracy)
+
+Implemented by `simocracy_post_skill` in `src/index.ts`:
+
+```ts
+// 1. The skill — same shape as SkillFormDialog writes today.
+const skill = await createSkill({
+  agent, did,
+  name,         // lowercase, kebab-case (e.g. "quadratic-funding")
+  description,  // SKILL.md trigger text — when an agent should load it
+  body,         // markdown instructions, no YAML frontmatter
+});
+
+// 2. The sim-attribution sidecar — required, since attribution is the
+//    whole point of this tool.
+await createSkillHistory({
+  agent, did,
+  skillUri:        skill.uri,
+  skillName:       name,
+  skillDescription: description,
+  simUri:          loadedSim.uri,
+  simName:         loadedSim.name,
+});
+```
+
+Both writes go to the **user's** PDS via their OAuth session — same
+auth path that already powers `simocracy_post_comment`,
+`simocracy_post_proposal`, and `simocracy_update_sim`. The write is
+gated on `/sim login` plus sim ownership (the sim must live in the
+signed-in DID's repo) — the sidecar uses `assertRepoOwnsSimUri`
+as defense-in-depth, identical to the comment / proposal paths.
+
+If the sidecar write fails after the skill succeeds, **the skill is
+not rolled back** — it just shows up unattributed until the user
+retries. We don't roll back, because rolling back leaves an
+orphaned tombstone in the user's repo that's harder to reason about
+than a missing badge. The tool surfaces a `sidecarWarning` in the
+result so the LLM can decide whether to retry.
+
+### What we deliberately don't do
+
+- **Skill editing.** Create-only for now. Editing an existing
+  skill would mean either a `putRecord` at a known rkey (no good
+  way to discover it from the loaded sim — skills have no `sim`
+  ref) or a `findRkeyForSkill` join through the history sidecar.
+  Out of scope until a real edit use case shows up.
+- **Skill deletion.** Same reason. The user can delete via the
+  webapp.
+- **Cross-skill linking.** Pi doesn't try to inject prerequisite /
+  related-skill references. The skill body is whatever the sim
+  writes; if it wants to reference another skill it includes the
+  AT-URI inline.
+
+---
+
+## Read path (proposed simocracy-v2 changes)
+
+Mirrors the comment + proposal renderer changes in shape, applied
+to the skills gallery / detail views.
+
+### 1. Skills gallery query — pull history records in parallel
+
+After fetching the skills via `fetchSkills`, fetch all
+`org.simocracy.history` records (capped, like notifications does)
+and build a `Map<skillUri, HistoryRecord>` keyed on `subjectUri`.
+Filter to `type === "skill"` and `subjectCollection ===
+"org.simocracy.skill"`. Attach `simUri`, `simName`, and a
+resolved `simAvatarUrl` to each skill in the response that has a
+match. Sim avatar resolution can reuse `fetchAllSimsWithMeta()` —
+no extra round-trips per skill.
+
+### 2. Extend the skill type
+
+```ts
+export interface SkillRecord {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+No change to `SkillFormDialog` — that path stays for human
+authors. Sim-authored skills come from the CLI today, and a
+future "draft as sim" button in the dialog would bundle both
+writes the same way pi-simocracy does.
+
+### 3. Skill card — sim badge
+
+In `SkillCard` (`components/skills/skills-gallery.tsx`), when
+`skill.simUri` is set:
+
+- Render the sim sprite inline next to the title (32×32 walk-1
+  frame), the way proposal cards do.
+- Render the byline as `🐾 {simName} · drafted by @{userHandle}`
+  so attribution stays unambiguous (the sim "drafted" it; the human
+  published and owns the record).
+- Add a `[sim]` mono-uppercase badge alongside the existing
+  meta pills.
+- Link the sim name to `/sims/{did}/{rkey}` via the existing slug
+  resolver.
+
+Skills without `simUri` keep rendering exactly as today — no
+regression for human-authored skills.
+
+### 4. SKILL.md reconstruction
+
+The `/skills/[did]/[rkey]/skill.md` route stays unchanged — the
+served file is the canonical SKILL.md any agent harness loads,
+and sim attribution is metadata for the *gallery*, not the
+SKILL.md contents. Keeping attribution out of the served file
+means a sim-authored skill can be loaded by any external harness
+(Anthropic skills CLI, custom agent runtimes, …) without that
+harness needing to understand Simocracy lexicons.
+
+---
+
+## Querying sim-authored skills
+
+For "show me everything my sim has published":
+
+```ts
+const histories = await fetchHistory()  // existing helper
+const mySimSkills = histories.filter(h =>
+  h.event.type === "skill" &&
+  h.event.simUris?.includes(mySimUri)
+)
+```
+
+Each result has `subjectUri` (the skill URI) and `content`
+(denormalized description). Resolve the skill URI for the full
+record. Same query shape the notifications system already uses
+for chat / comment / proposal events — no new indexer queries
+needed.
+
+---
+
+## Status
+
+- ✅ Implemented in pi-simocracy `simocracy_post_skill` (this repo)
+- ⏳ Renderer changes pending in simocracy-v2 (sim badge on skill
+  cards, history-sidecar join in `fetchSkills` / skill detail page)
+- ✅ No new lexicons — uses the existing `org.simocracy.skill` and
+  `org.simocracy.history` records as-is
+
+The skill + history pair is being written today. Every pi-authored
+skill carries the sim badge (history sidecar) so once
+simocracy-v2's renderer change lands the attribution surfaces
+automatically — no migration, no backfill needed for new
+submissions. Pre-renderer, pi-authored skills appear identically
+to human-authored skills on `simocracy.org/skills`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Pi extension: load a Simocracy sim into your chat — see its pixel-art sprite render inline in the terminal and roleplay with it.",
   "type": "module",
   "author": "David Dao <david@gainforest.earth> (https://github.com/daviddao)",

package/src/index.ts

@@ -61,6 +61,14 @@
  *                             `type: "proposal"`. Same write pattern
  *                             as `simocracy_post_comment`. Requires
  *                             /sim login + sim ownership.
+ *  - `simocracy_post_skill`   Publish an Anthropic-style agent skill
+ *                             (`org.simocracy.skill`) on behalf of
+ *                             the loaded sim, plus an
+ *                             `org.simocracy.history` sidecar with
+ *                             `type: "skill"`. Same write pattern as
+ *                             `simocracy_post_comment` /
+ *                             `simocracy_post_proposal`. Requires
+ *                             /sim login + sim ownership.
  *  - `simocracy_lookup_record` Look up a sim / proposal / gathering /
  *                             decision / comment by AT-URI or fuzzy
  *                             name and return its details + comment
@@ -132,6 +140,8 @@ import {
   createProposal,
   createProposalContext,
   createProposalHistory,
+  createSkill,
+  createSkillHistory,
   createStyle,
   findRkeyForSim,
   getAuthenticatedAgent,
@@ -811,6 +821,28 @@ const PostProposalToolParams = Type.Object({
   ),
 });
 
+const PostSkillToolParams = Type.Object({
+  name: Type.String({
+    description:
+      "Skill identifier — lowercase, kebab-case (e.g. `quadratic-funding`). Maps to the `name` field of the SKILL.md YAML frontmatter. Required, max 100 characters.",
+    minLength: 1,
+    maxLength: 100,
+    pattern: "^[a-z][a-z0-9-]*$",
+  }),
+  description: Type.String({
+    description:
+      "Skill triggering description — what the skill does AND when an agent should load it. Maps to the `description` field of the SKILL.md YAML frontmatter; this is the primary signal an agent uses to decide whether to load the skill, so make it specific and a little pushy. Required, max 1024 characters.",
+    minLength: 1,
+    maxLength: 1024,
+  }),
+  body: Type.String({
+    description:
+      "Markdown body of SKILL.md, without YAML frontmatter — the actual instructions. Anthropic recommends keeping this under ~500 lines. Required, max 50000 characters.",
+    minLength: 1,
+    maxLength: 500000,
+  }),
+});
+
 const LookupRecordToolParams = Type.Object({
   query: Type.String({
     description:
@@ -1757,6 +1789,131 @@ export default async function simocracy(pi: ExtensionAPI) {
     },
   });
 
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_post_skill
+  //
+  // Publish an Anthropic-style agent skill (`org.simocracy.skill`) on
+  // behalf of the loaded sim. Two records are written to the user's
+  // PDS, mirroring `simocracy_post_comment` / `simocracy_post_proposal`:
+  //
+  //   1. org.simocracy.skill      the skill record itself, in the same
+  //      wire shape simocracy.org's `SkillFormDialog` writes today, so
+  //      it renders identically on /skills.
+  //   2. org.simocracy.history    sidecar with type="skill",
+  //      simUris=[loadedSim], subjectUri=<skill uri>. Renderers that
+  //      understand the join show the sim badge; others see a regular
+  //      user-authored skill — graceful degradation, zero lexicon
+  //      changes.
+  //
+  // See `docs/SIM_AUTHORED_SKILLS.md` for the design rationale.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_post_skill",
+    label: "Publish a Simocracy skill as the loaded sim",
+    description:
+      "Publish an Anthropic-style agent skill (`org.simocracy.skill`) on behalf of the currently loaded sim. The sim should write the `name` (lowercase kebab-case identifier), `description` (what the skill does AND when an agent should load it — the primary trigger signal), and `body` (the markdown instructions, without YAML frontmatter) in their own voice; their persona is already in your system prompt. Writes TWO records to the user's PDS: (1) the `org.simocracy.skill` record itself in the same shape simocracy.org's SkillFormDialog writes today, and (2) an `org.simocracy.history` sidecar with `type: \"skill\"` attributing the skill to the loaded sim. Use this when the user asks the sim to write, publish, or share a skill — e.g. \"Mr Meow, draft a skill for evaluating cat-sanctuary proposals\" or \"publish a skill on quadratic funding\". The skill appears on simocracy.org/skills and can be loaded into any agent harness via /skills/<did>/<rkey>/skill.md. Anthropic recommends keeping `body` under ~500 lines. Requires /sim login + a loaded sim the user owns.",
+    parameters: PostSkillToolParams,
+    async execute(_id, { name, description, body }) {
+      if (!loadedSim) {
+        throw new Error(
+          "No sim loaded. Call simocracy_load_sim first — skills are published on behalf of a specific sim.",
+        );
+      }
+      let auth;
+      try {
+        auth = await assertCanWriteToSim(loadedSim, {
+          action: "publish a skill as",
+        });
+      } catch (err) {
+        if (err instanceof NotSignedInError || err instanceof NotSimOwnerError) {
+          throw new Error(err.message);
+        }
+        throw err;
+      }
+      let pdsAgent;
+      try {
+        ({ agent: pdsAgent } = await getAuthenticatedAgent());
+      } catch (err) {
+        if (err instanceof NotSignedInError) throw new Error(err.message);
+        throw new Error(`ATProto auth failed: ${(err as Error).message}`);
+      }
+
+      let skill;
+      try {
+        skill = await createSkill({
+          agent: pdsAgent,
+          did: auth.did,
+          name,
+          description,
+          body,
+        });
+      } catch (err) {
+        throw new Error(`Skill write failed: ${(err as Error).message}`);
+      }
+
+      let sidecarUri: string | undefined;
+      let sidecarWarning: string | undefined;
+      try {
+        const history = await createSkillHistory({
+          agent: pdsAgent,
+          did: auth.did,
+          skillUri: skill.uri,
+          skillName: name,
+          skillDescription: description,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+        });
+        sidecarUri = history.uri;
+      } catch (err) {
+        // Don't roll back — the skill is already on the user's PDS.
+        // The sidecar can be re-written later. Surface the warning so
+        // the LLM can decide whether to retry.
+        sidecarWarning = `Sim-attribution sidecar failed: ${(err as Error).message}`;
+      }
+
+      // Public URLs the LLM can hand back to the user. The skill page
+      // is served by simocracy-v2's /skills/[did]/[rkey] route; the
+      // .md endpoint reconstructs the full SKILL.md (frontmatter + body)
+      // for any agent harness that wants to load it.
+      const did = encodeURIComponent(loadedSim.did);
+      const rkey = encodeURIComponent(skill.rkey);
+      const pageUrl = `https://www.simocracy.org/skills/${did}/${rkey}`;
+      const skillMdUrl = `https://www.simocracy.org/skills/${did}/${rkey}/skill.md`;
+
+      const lines = [
+        `Published skill as ${loadedSim.name}${loadedSim.handle ? ` (@${loadedSim.handle})` : ""}:`,
+        `  name:        ${name}`,
+        `  skill URI:   ${skill.uri}`,
+        `  page:        ${pageUrl}`,
+        `  SKILL.md:    ${skillMdUrl}`,
+      ];
+      if (sidecarUri) {
+        lines.push(`  attribution: ${sidecarUri}  (org.simocracy.history sidecar)`);
+      } else if (sidecarWarning) {
+        lines.push(`  WARNING:     ${sidecarWarning}`);
+        lines.push(
+          `               The skill is published but will appear unattributed until a history sidecar is written.`,
+        );
+      }
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+        details: {
+          skillUri: skill.uri,
+          skillRkey: skill.rkey,
+          skillCid: skill.cid,
+          name,
+          description,
+          pageUrl,
+          skillMdUrl,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+          sidecarUri,
+          sidecarWarning,
+        },
+      };
+    },
+  });
+
   // -------------------------------------------------------------------------
   // Tool: simocracy_lookup_record
   //

package/src/writes.ts

@@ -131,6 +131,7 @@ const COLLECTION_COMMENT = "org.impactindexer.review.comment";
 const COLLECTION_HISTORY = "org.simocracy.history";
 const COLLECTION_PROPOSAL = "org.hypercerts.claim.activity";
 const COLLECTION_PROPOSAL_CONTEXT = "org.simocracy.proposalContext";
+const COLLECTION_SKILL = "org.simocracy.skill";
 
 /**
  * Defense-in-depth: every write helper below verifies the target
@@ -594,6 +595,117 @@ export async function createProposalHistory(opts: {
   };
 }
 
+/**
+ * POST `org.simocracy.skill` (an Anthropic-style agent skill).
+ *
+ * The lexicon stores the SKILL.md frontmatter (`name`, `description`)
+ * as separate fields and the markdown body in `body`, so the indexer
+ * can filter on metadata cheaply without parsing markdown. The full
+ * SKILL.md is reconstructed at serve time by simocracy.org's
+ * `/skills/[did]/[rkey]/skill.md` route.
+ *
+ * Skills are NOT 1:1 with sims — the lexicon has no `sim` ref. They
+ * live in the *user's* own PDS exactly the way simocracy.org's
+ * `SkillFormDialog` writes them today, so a sim-authored skill
+ * renders identically to a human-authored skill on the gallery.
+ * Sim attribution is a sidecar `org.simocracy.history` record
+ * written by `createSkillHistory` below — same pattern as comments
+ * and proposals. See `docs/SIM_AUTHORED_SKILLS.md` for the design.
+ */
+export async function createSkill(opts: {
+  agent: Agent;
+  did: string;
+  name: string;
+  description: string;
+  body: string;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  const name = opts.name.trim();
+  if (!name) throw new Error("Skill name is required.");
+  const description = opts.description.trim();
+  if (!description) throw new Error("Skill description is required.");
+  const body = opts.body.trim();
+  if (!body) throw new Error("Skill body is required.");
+  // Lexicon caps (mirrored from lexicons/org/simocracy/skill.json):
+  //   name        ≤ 100 graphemes (maxLength 1000)
+  //   description ≤ 1024 graphemes (maxLength 10000)
+  //   body        ≤ 50000 graphemes (maxLength 500000)
+  // Slice on JS string length is a conservative approximation of grapheme
+  // count — it never exceeds the limit, occasionally trims early on rare
+  // multi-codepoint clusters. Same approach used elsewhere in this module.
+  const record = {
+    $type: COLLECTION_SKILL,
+    name: name.slice(0, 1000),
+    description: description.slice(0, 10000),
+    body: body.slice(0, 500000),
+    createdAt: new Date().toISOString(),
+  };
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_SKILL,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
+/**
+ * Sim-attribution sidecar for a skill.
+ *
+ * Mirrors `createCommentHistory` and `createProposalHistory` exactly —
+ * same `org.simocracy.history` lexicon, same join-key shape, just
+ * `type: "skill"` and `subjectCollection: "org.simocracy.skill"`.
+ * The lexicon's `type` field is free-form string and the indexer
+ * already accepts new event types as they appear (history.json
+ * documents this explicitly).
+ *
+ * Writes to the *user's* own PDS — the attribution is an event the
+ * user triggered and naturally belongs in their history.
+ */
+export async function createSkillHistory(opts: {
+  agent: Agent;
+  did: string;
+  skillUri: string;
+  skillName: string;
+  skillDescription: string;
+  simUri: string;
+  simName: string;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  // Defense-in-depth: the sim must live in the same repo we're writing
+  // to. The skill record itself isn't sim-owned, but the history
+  // sidecar *claims attribution to* a sim — only the sim's owner can
+  // make that claim.
+  assertRepoOwnsSimUri(opts.did, opts.simUri);
+  const skillName = opts.skillName.trim();
+  const description = opts.skillDescription.trim();
+  const record: Record<string, unknown> = {
+    $type: COLLECTION_HISTORY,
+    type: "skill",
+    actorDid: opts.did,
+    simNames: [opts.simName].slice(0, 10),
+    simUris: [opts.simUri].slice(0, 10),
+    subjectUri: opts.skillUri,
+    subjectCollection: COLLECTION_SKILL,
+    subjectName: skillName.slice(0, 500),
+    createdAt: new Date().toISOString(),
+  };
+  if (description) {
+    record.content = description.slice(0, 5000);
+  }
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_HISTORY,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
 /**
  * Best-effort lookup of an existing rkey by listing the collection
  * and finding the record whose `sim.uri` matches. Used by the Apply