Create, retrieve, query, and update Artifacts — tangible deliverables produced by the project. Use when storing or retrieving documents, designs, datasets, build outputs, slide decks, or any completed deliverable that should be registered in the project catalog.
Artifacts are tangible deliverables — documents, design files, datasets, build outputs, slide decks, videos, or external URLs. Unlike Notes (thoughts in transit), Artifacts are completed deliverables registered in the project catalog. Unlike WorkItems (units of tracked work), Artifacts have no state lifecycle — they exist or they don't.
Two storage patterns are equally valid:
spec.location may reference the file's own path or
be omitted. Use for documents that belong in the repository (PRDs,
runbooks, research reports, work instructions).spec.location is the canonical address.
processkit stores only the metadata card.MCP server. This skill ships a self-contained MCP server at
mcp/server.py(PEP 723 script — requiresuvand Python ≥ 3.10 on PATH). Agent harnesses reach its tools by reading a single MCP config file at startup, so the contents of must be merged into the harness's MCP config and placed at the harness-specific path before this skill is usable.
mcp/mcp-config.jsonspec.kind classifies the artifact:
| kind | When to use |
|---|---|
document | Prose documents — PRDs, runbooks, reports, guides |
design | Design files — Figma, Excalidraw, wireframes |
dataset | Structured data — CSV, JSON, Parquet |
build | Compiled outputs — binaries, bundles, tarballs |
slides | Presentation decks — PPTX, PDF slide decks |
video | Recorded content — demos, walkthroughs |
spec | Formal specifications — OpenAPI, JSON Schema, proto |
diagram | Architecture and flow diagrams |
url | External web resources, dashboards, hosted tools |
other | Anything that doesn't fit the above |
Create an Artifact when:
Do not create Artifacts for in-progress work — use a WorkItem or a Note while the thing is still being made.
kind from the table above.name.location for pointer artifacts (URL, path, bucket key).
Omit or set to the entity file path for self-hosted artifacts.produced_by to the WorkItem or Process ID that produced it.owner to the responsible Actor ID.tags for retrieval (topic, project, format, etc.).context/artifacts/ART-<id>.md.artifact.created.Common queries via query_artifacts:
document artifacts)index-managementUse update_artifact to revise metadata (new version, updated
location, changed owner). To replace the body content of a
self-hosted artifact, update the Markdown body via update_artifact
or by editing the file directly followed by reindex.
Agent-specific failure modes:
location for pointer artifacts. If the content lives
outside the repository (a URL, a cloud bucket path, a release
binary), location is the only way to find it. Omitting it makes
the catalog entry useless as a pointer.create_artifact, run
query_artifacts and check for an existing entry with the same
name or location. Duplicates create confusion about which entry is
canonical.produced_by. Linking the artifact back to the
WorkItem or Process that produced it is cheap and makes the
catalog navigable. Always set it when the provenance is known.See src/context/schemas/artifact.yaml for the authoritative schema.
| Field | Required | Description |
|---|---|---|
name | yes | Human-readable name |
kind | yes | Subtype (see table above) |
location | no* | Path, URL, or storage key (* required for pointers) |
format | no | File format or MIME type (e.g. pdf, image/png) |
version | no | Version identifier for the artifact |
checksum | no | Hash for integrity verification |
owner | no | Actor ID responsible for the artifact |
produced_by | no | Entity ID (WorkItem, Process) that produced this |
produced_at | no | ISO 8601 datetime when the artifact was produced |
tags | no | Freeform tags for retrieval |
| State | Use |
|---|---|
| Idea, half-formed thought | Note |
| In-progress document | Note or WorkItem body |
| Finished, shareable deliverable | Artifact |
| External resource to reference | Artifact (pointer) |
A WorkItem is the unit of work that produces an Artifact. Link the
two via spec.produced_by on the Artifact (pointing to the WorkItem
ID). This gives a navigable trail from deliverable back to the work
that created it.