<skill name="kortix-artifacts">
<checklist>
Before every publish:
1. **Title = a name**, 2–4 words, no colon, dash or arrow: `--title "Scheduler migration"`,
never `--title "Scheduler migration: off the cron VM"`. The explanation goes in
`--description`.
2. **Share when asked.** "So the team can review it", "share with the team" or
"for the project" → add `--visibility project`, on the publish or with
`kortix artifacts share <id> --visibility project`. In a private channel
(`/drives/README.md` says so) never use `--visibility project` or `public`:
the artifact stays private to the channel's members.
3. **Answer first**: the recommendation or result is the first paragraph.
4. **One artifact per thing.** Revising an existing one? Save into it (`--id`).
5. **Hand it over with `show`**: `url` = the artifact's app link, `title` = its
name. The user sees it in the chat and opens it beside the chat. Then one
line on what it shows.
</checklist>
<overview>
An artifact is a folder in the project's Drive, shared. Its files are ordinary
files (`index.md` for a doc, `index.html` plus its images and scripts for a
page). The artifact adds a place in the Artifacts gallery, a viewer, version
history (the Drive history of that folder) and share links. Keep a code change
in the repository.
Before you write one, read references/design.md (the page contract and the
design method). For any diagram, read references/diagrams.md.
</overview>
<when>
Make an artifact when the result is something the user will read, keep, share,
present or come back to: a plan, a spec, a report, a comparison, a deck, a
dashboard, a tool. Also make one when an answer would run past about a screen
of structured content (headings, tables, steps).
Answer in chat when the answer is a few sentences, a quick fact, or a short
list. A code change belongs in the repository, not in an artifact.
Change the existing artifact when the user asks to revise, extend or fix one.
Never publish a second copy (see <update>).
</when>
<method>
1. **Read the request.** Name the subject, the reader and the page's single
job. Choose the type:
- **doc** for words people read and edit (plans, specs, reports, memos);
- **html** for anything that needs layout, charts, interaction or slides.
Choose the treatment (utilitarian, UI or editorial) from
references/design.md.
2. Gather real content first. Get real numbers with units and dates, real
names of things, the user's own terms. Never use lorem ipsum. If data is
missing, the page says so.
3. Plan. For html, write the token plan (colors, type roles, a layout
line) as the :root block before anything else. For a doc, write the
heading outline first.
4. Write it once, well. Lead with the answer. Follow the fundamentals in
references/design.md.
5. Name it. Give it a --title and a one-sentence --description (rules
below).
6. Publish, look once, fix once. See "Check once" in
references/design.md. No loops.
7. Hand it over. Call show with the app link (url) and the name
(title): the chat shows the artifact itself, and the user opens it beside
the chat. End your reply with one line on what the
artifact shows. Never paste its content into the chat. Mention the design
in at most one plain sentence.
</method>
<naming>
The title is the artifact's name in the gallery, beside dozens of others.
- Write a name, not a caption: a short noun phrase, usually 2–4 words,
specific to the subject ("Q3 churn report", "Pricing page v2", "Card deck").
A page that answers one question may take that question as its name.
- Use the user's own name for the thing when they have one.
- Never use a bare category ("Report", "Dashboard", "Plan"). Never add an
explanation after a dash, a colon or an arrow:
| Wrong | Right |
|---|
Docs search migration: hosted vendor → Postgres FTS | Docs search migration |
Q3 Report – churn, revenue and retention | Q3 churn report |
Dashboard | Support queue health |
Pass the name with --title. The doc's own # heading may say more.
- Put the explanation in
--description, one sentence: the gallery shows it
under the title.
- Keep the title stable across saves.
</naming>
<planning>
Plans, proposals and decision records are the most common artifact. Make each
one a **doc**, in this order. Skip a section that has nothing true to say.
# <Name>, then the recommendation or the decision asked for in the
first paragraph: what to do, by when, and what it costs in time or risk.
- The problem, stated as the problem ("signups drop 40% at the email
step"), not as a pre-chosen solution.
- Options: a table, one row per option, with columns for what matters
(effort, risk, reversibility, what it unblocks). If the options differ in
structure, add one mermaid diagram that shows the difference.
- The plan: numbered steps, each with an owner or a done-when.
- Risks and unknowns: one line each (what, why it matters, what resolves
it).
- Next steps: a task list (
- [ ]) the reader can tick in the doc.
Write it for a reader who decides without asking you a question. Revise the
same artifact as the plan changes: its history keeps every earlier version.
</planning>
<types>
| Type | For | The file |
|---|---|---|
| `doc` | specs, reports, memos, plans | a **Markdown** file (`report.md`). Kortix renders and styles it; people edit it in place and export it as PDF. |
| `html` | decks, dashboards, mockups, tools | an **HTML** file, or a folder with `index.html` and its assets. Served exactly as written. |
kortix artifacts types <type> prints the format rules and a starter.
doc: one # Title, then headings, paragraphs, bold, italic,
code, links, bulleted, numbered and task lists (- [ ]), quotes, code
blocks, tables, ```mermaid diagrams, images and videos (files in media/ next to
index.md, referenced relatively), ---. No HTML layout, CSS or scripts.
Need charts or layout? Make an html artifact.
html: a complete page, served exactly as written: write the <!doctype>,
the viewport meta and the <title> yourself. It runs sandboxed (no cookies;
storage may throw; no access to Kortix). Its images, data and scripts sit in
the same folder and load by relative path. Load libraries from a CDN at a
pinned version (Chart.js for charts, Reveal.js for decks). It must work from
400 px to a large screen and in light and dark. The full contract is in
references/design.md.
</types>
<publish>
Two ways, same result:
kortix artifacts publish report.md --title "Q3 churn report" # uploads to your Artifacts folder in Drive
kortix artifacts publish ./deck # a folder with index.html
kortix artifacts add /Company/Plans/roadmap # shares a folder already in Drive (index.md or index.html)
A .md file is a doc; anything else is html. The command prints the artifact
id, its path in Drive and its app link. Hand it over with show (the app link
as url) and one line on what it shows. Never paste the content into the chat.
A new artifact is private: the person who runs this session (and you) can
see it. Share it when the user asks. "Share it with the team", "something the
team can review" or "for everyone on the project" each mean
--visibility project; pass it on the first publish. Named people mean
--with. Only an explicit "public" or "anyone with the link" means public:
kortix artifacts share <id> --visibility project # every project member
kortix artifacts share <id> --with ada@example.com # chosen people (private)
kortix artifacts share <id> --visibility public # anyone with the link
Ask before public: a public link works without a login. Never publish
secrets, tokens or customer data.
</publish>
<update>
Change the artifact, never publish a second one. Edit its file in Drive, or:
kortix artifacts pull <id> ./work # prints the entry_version
# edit ./work/<file>
kortix artifacts publish ./work/<file> --id <id> --base-version <entry_version>
--base-version refuses the save (exit 3, version_conflict) when someone
saved after you pulled, for example a person editing the doc: pull again,
merge, save. kortix artifacts versions <id> lists every save from the Drive
history; restore <id> <version-id> writes one back as a new save.
kortix artifacts rm <id> stops sharing; the files stay in Drive.
If the request also asks to share ("so the team can review it"), share the
artifact you saved: kortix artifacts share <id> --visibility project.
</update>
<quality>
- Say the answer first: the doc's opening paragraph, the deck's title slide,
the dashboard's header.
- Real content only. Every number has a unit and a date. Every chart is drawn
to scale.
- Decks: one idea per slide, large type, arrow keys to move.
- Never publish secrets, tokens or customer data. Use synthetic examples
marked as examples.
</quality>
<commands>
| Command | Does |
|---|---|
| `kortix artifacts types [<type>]` | types; one type's format and starter |
| `kortix artifacts publish <file\|dir> [--title --description --visibility]` | upload and share |
| `kortix artifacts add <folder> [--title --visibility]` | share a folder already in Drive; an artifact is always a folder, so a lone file is refused (publish it instead) |
| `kortix artifacts publish <file\|dir> --id <id> [--base-version v]` | save new content |
| `kortix artifacts ls [--mine\|--shared\|--pinned] [--type t] [--search q]` | list |
| `kortix artifacts info <id>` / `open <id>` | details, path, links |
| `kortix artifacts cat <id> [path] [--version v]` / `pull <id> <dir>` | read |
| `kortix artifacts share <id> --visibility … [--with …]` | share |
| `kortix artifacts versions` / `restore` / `rename` / `pin` / `unpin` / `rm` | manage |
Add --json for machine-readable output. Permissions (a role's, and for an
agent its kortix_permissions in kortix.yaml):
| Permission | Lets you |
|---|
project.artifact.read | list, open, read versions and files |
project.artifact.write | publish, add, save, restore; rename and share your own |
project.artifact.manage | rename, share or stop sharing anyone's |
project.artifact.public | give an artifact a public link |
Saving also needs write access to the folder in Drive. A refused public link
answers 403 public_link_forbidden: share with the project instead and tell
the user.
</commands>
</skill>