@rayul/kordis 0.0.1

package/README.md

@@ -0,0 +1,53 @@
+# @rayul/kordis
+
+> The CLI binary is **`kordis`** — only the npm package name is scoped.
+
+Public registry CLI for agentic-coding packages — skills, project rules, MCP servers, hooks, custom agents.
+
+## Quick start
+
+```bash
+npx @rayul/kordis@latest setup           # one-time: register kordis with Claude Code / Codex / Gemini CLI
+npx @rayul/kordis@latest search sql      # find a skill
+npx @rayul/kordis@latest read rayul/sql-reviewer   # JIT-load into your agent context
+```
+
+Or install globally:
+
+```bash
+npm install -g @rayul/kordis
+kordis setup
+```
+
+`kordis setup` injects a guide block into your agent tools' global instruction files (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`) so the agent recognises `kordis` automatically in future sessions. The injection is idempotent — safe to re-run.
+
+## Commands
+
+| command | purpose |
+|---|---|
+| `kordis search <query>` | search the registry |
+| `kordis info <slug>` | inspect a package |
+| `kordis read <slug>` | JIT-fetch body into agent context (skill / project-rules / custom-agent only) |
+| `kordis pull <slug>` | install into the current project (mcp-server / hook) |
+| `kordis push <file>` | publish a new package or version |
+| `kordis login` / `logout` / `whoami` | identity |
+| `kordis setup` | inject usage guide into Claude Code / Codex / Gemini CLI globals |
+
+Pass `--json` on any command to get machine-readable output.
+
+## Configuration
+
+| env var | purpose | default |
+|---|---|---|
+| `KORDIS_API_URL` | registry endpoint | `https://api.kordis.dev` |
+| `KORDIS_HOME` | config + token fallback dir | `~/.kordis` |
+
+Refresh and access tokens are stored in the OS keychain via `keytar` (with a file-based fallback at `~/.kordis/.tokens.json`, mode `0600`, when keytar is unavailable).
+
+## Docs
+
+The agent guide that `setup` injects is also shipped as `assets/KORDIS.md` in this package.
+
+## License
+
+MIT

package/assets/KORDIS.md

@@ -0,0 +1,86 @@
+---
+name: kordis
+description: Use Kordis to discover, install, and publish agentic-coding packages (skills, project rules, MCP servers, custom agents, hooks). Invoke whenever the user says "find a skill for X", "install Y", "publish this as a skill", "share this prompt", or mentions a `{username}/{slug}` package identifier.
+version: 0.0.1
+---
+
+# Kordis Skill
+
+Kordis is the public registry for agentic-coding packages. You install and publish by shelling out to the `kordis` CLI — never by editing tool-specific files (CLAUDE.md, `.cursorrules`, `.mcp.json`, etc.) manually.
+
+## When to invoke
+
+- User asks to find / try / install a skill, rule, agent, MCP server, or hook.
+- User references a `{username}/{slug}` identifier.
+- User says "publish this", "share this to Kordis", "push this rule".
+- User asks what packages they have installed or what's trending.
+
+## Primary verbs
+
+| verb | purpose | sub-skill |
+|------|---------|-----------|
+| `kordis search <query>` | find packages | `SEARCH` |
+| `kordis info <full_slug>` | inspect a package | `READ` |
+| `kordis read <full_slug>` | **JIT** — fetch body into your context, no install | `READ` |
+| `kordis pull <full_slug>` | install into the current project | `READ` |
+| `kordis push <file>` | publish a new package or version | `WRITE` |
+| `kordis whoami` / `login` / `logout` | identity + session | `SOCIAL` |
+
+Always pass `--json` when you need the response programmatically. Human output is for the user; agent parsing lives behind `--json`.
+
+## JIT read vs install — choose deliberately
+
+Two ways to use a package's guidance. Pick the one that matches the user's intent, not your own convenience.
+
+| Mode | Use when | Effect |
+|------|----------|--------|
+| `kordis read <slug>` | **One-shot sub-task.** You'll consult the skill once for the current task and move on. The user said "do X for me", "handle this file", "explain how Y works." | Body returned to your context (stdout). Nothing written to disk. |
+| `kordis pull <slug>` | **Long-term adoption.** The user said "install Y", "make this project use Z", "set up A for ongoing work." The skill should keep working in future sessions. | Files written into the project's tool-specific path. |
+
+**Default to `read`** when you spontaneously realize a Kordis skill exists for the task at hand. **Default to `pull`** when the user explicitly asks to adopt a package.
+
+Restrictions on `read`:
+- Eligible types: `skill`, `project-rules`, `custom-agent` (text-bearing).
+- Ineligible: `mcp-server`, `hook`. The CLI errors with `jit_blocked` (exit 33, flag `type_ineligible`) — fall back to `kordis pull`.
+- Trust gate: only `review_status=passed` versions are returned by default. For `pending_review`, re-run with `--allow-pending` only after telling the user the skill has not been AI-reviewed yet.
+
+Pin a version when reproducibility matters: `kordis read foo/bar@1.2.0`. A bare slug fetches the latest passed version; the response always includes the resolved version so you can record it.
+
+## Attribution
+
+The `read` response includes an `attribution` string (e.g. `"following rayul/hwp-reader@0.3.1"`). Including it in your reply to the user is **recommended**:
+- It lets the user verify which guidance you followed.
+- It's how creators see their work being used.
+- It supports reproducibility (the user can repeat the workflow with the same version).
+
+Skip it only if it would clutter a non-technical answer (e.g. the user asked a casual question and a one-line credit at the end is enough). When in doubt, include it.
+
+## Identity
+
+`full_slug` is always `{username}/{slug}`. Usernames are immutable; slugs are lowercase-with-hyphens. Versions are semver.
+
+## Sub-skills
+
+- `kordis read rayul/kordis-search` — searching / browsing / trending / rising
+- `kordis read rayul/kordis-read` — info / content / pull / dependency handling
+- `kordis read rayul/kordis-write` — authoring + publishing + updating
+- `kordis read rayul/kordis-social` — comments, stars, notifications, mod actions
+
+Load the sub-skill that matches the user's intent rather than repeating the detail here.
+
+## Error handling
+
+The CLI's `--json` mode emits `{ error: { code, message, flags?, request_id? } }` on failure. Key codes:
+
+| code | action |
+|------|--------|
+| `not_authenticated` (exit 10) | run `kordis login`, then retry |
+| `validation_failed` (30) | fix the flags listed and retry |
+| `ai_review_rejected` (32) | explain to the user; do not auto-retry |
+| `conflict` (40) | slug taken → suggest a new name |
+| `rate_limited` (31) | wait `retry_after_seconds` |
+| `network_unreachable` (20) | retry with backoff |
+
+## Agent skills compliance
+
+The skill files Kordis ships respect the Agent Skills open spec verbatim — no Kordis-specific extensions leak into your `SKILL.md`. Kordis-internal metadata lives on the registry entry, not in the skill file. Install `kordis/agent-skills` for the canonical workflow if the user is authoring their own skills.

package/bin/kordis.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';