Artifact Management
Intro
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:
- Self-hosted: the artifact content is the Markdown body of the
entity file;
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).
- Pointer: the deliverable lives elsewhere (external URL, cloud
storage, build artifact);
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 — requires uv and Python ≥ 3.10
on PATH). Agent harnesses reach its tools by reading a single MCP
config file at startup, so the contents of mcp/mcp-config.json
must be merged into the harness's MCP config and placed at the
harness-specific path before this skill is usable.
Overview
Artifact kinds
spec.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 |
When to create an Artifact
Create an Artifact when:
- A deliverable is complete enough to reference and share.
- Something produced by the project should be discoverable later
(a report, a shipped binary, an approved design).
- A Note has been promoted to a finished document.
- A work item produced a document or design that should be cataloged.
Do not create Artifacts for in-progress work — use a WorkItem
or a Note while the thing is still being made.
Creating
- Choose
kind from the table above.
- Write a short, descriptive
name.
- Set
location for pointer artifacts (URL, path, bucket key).
Omit or set to the entity file path for self-hosted artifacts.
- Set
produced_by to the WorkItem or Process ID that produced it.
- Set
owner to the responsible Actor ID.
- Add
tags for retrieval (topic, project, format, etc.).
- Write the file to
context/artifacts/ART-<id>.md.
- Log
artifact.created.
Querying
Common queries via query_artifacts:
- All artifacts of a given kind (e.g., all
document artifacts)
- All artifacts owned by an actor
- All artifacts tagged with a given tag
- Full-text search via
index-management
Updating
Use 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.
Gotchas
Agent-specific failure modes:
- Creating an Artifact for in-progress work. An Artifact is a
completed deliverable. If the thing isn't done yet, use a WorkItem
(for tracked work) or a Note (for an idea still forming). Premature
Artifact registration pollutes the catalog with incomplete items.
- Omitting
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.
- Duplicate registration. Before
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.
- Using Artifact for ephemeral build outputs. Not every build
artifact needs a catalog entry. Register the ones that matter for
the release, for compliance, or for future reference. Registering
every intermediate build output creates noise.
- Forgetting
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.
Full reference
Full field list
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 |
Note vs Artifact decision rule
| State |
Use |
| Idea, half-formed thought |
Note |
| In-progress document |
Note or WorkItem body |
| Finished, shareable deliverable |
Artifact |
| External resource to reference |
Artifact (pointer) |
Relationship to WorkItems
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.
1---2name: artifact-management-23description: 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.4---56# Artifact Management78## Intro910Artifacts are tangible deliverables — documents, design files,11datasets, build outputs, slide decks, videos, or external URLs.12Unlike Notes (thoughts in transit), Artifacts are completed13deliverables registered in the project catalog. Unlike WorkItems14(units of tracked work), Artifacts have no state lifecycle — they15exist or they don't.1617Two storage patterns are equally valid:1819- **Self-hosted**: the artifact content is the Markdown body of the20 entity file; `spec.location` may reference the file's own path or21 be omitted. Use for documents that belong in the repository (PRDs,22 runbooks, research reports, work instructions).23- **Pointer**: the deliverable lives elsewhere (external URL, cloud24 storage, build artifact); `spec.location` is the canonical address.25 processkit stores only the metadata card.2627> **MCP server.** This skill ships a self-contained MCP server at28> `mcp/server.py` (PEP 723 script — requires `uv` and Python ≥ 3.1029> on PATH). Agent harnesses reach its tools by reading a single MCP30> config file at startup, so the contents of `mcp/mcp-config.json`31> must be merged into the harness's MCP config and placed at the32> harness-specific path before this skill is usable.3334## Overview3536### Artifact kinds3738`spec.kind` classifies the artifact:3940| kind | When to use |41|------------|---------------------------------------------------------|42| `document` | Prose documents — PRDs, runbooks, reports, guides |43| `design` | Design files — Figma, Excalidraw, wireframes |44| `dataset` | Structured data — CSV, JSON, Parquet |45| `build` | Compiled outputs — binaries, bundles, tarballs |46| `slides` | Presentation decks — PPTX, PDF slide decks |47| `video` | Recorded content — demos, walkthroughs |48| `spec` | Formal specifications — OpenAPI, JSON Schema, proto |49| `diagram` | Architecture and flow diagrams |50| `url` | External web resources, dashboards, hosted tools |51| `other` | Anything that doesn't fit the above |5253### When to create an Artifact5455Create an Artifact when:5657- A deliverable is complete enough to reference and share.58- Something produced by the project should be discoverable later59 (a report, a shipped binary, an approved design).60- A Note has been promoted to a finished document.61- A work item produced a document or design that should be cataloged.6263Do **not** create Artifacts for in-progress work — use a WorkItem64or a Note while the thing is still being made.6566### Creating67681. Choose `kind` from the table above.692. Write a short, descriptive `name`.703. Set `location` for pointer artifacts (URL, path, bucket key).71 Omit or set to the entity file path for self-hosted artifacts.724. Set `produced_by` to the WorkItem or Process ID that produced it.735. Set `owner` to the responsible Actor ID.746. Add `tags` for retrieval (topic, project, format, etc.).757. Write the file to `context/artifacts/ART-<id>.md`.768. Log `artifact.created`.7778### Querying7980Common queries via `query_artifacts`:8182- All artifacts of a given kind (e.g., all `document` artifacts)83- All artifacts owned by an actor84- All artifacts tagged with a given tag85- Full-text search via `index-management`8687### Updating8889Use `update_artifact` to revise metadata (new version, updated90location, changed owner). To replace the body content of a91self-hosted artifact, update the Markdown body via `update_artifact`92or by editing the file directly followed by reindex.9394## Gotchas9596Agent-specific failure modes:9798- **Creating an Artifact for in-progress work.** An Artifact is a99 completed deliverable. If the thing isn't done yet, use a WorkItem100 (for tracked work) or a Note (for an idea still forming). Premature101 Artifact registration pollutes the catalog with incomplete items.102- **Omitting `location` for pointer artifacts.** If the content lives103 outside the repository (a URL, a cloud bucket path, a release104 binary), `location` is the only way to find it. Omitting it makes105 the catalog entry useless as a pointer.106- **Duplicate registration.** Before `create_artifact`, run107 `query_artifacts` and check for an existing entry with the same108 name or location. Duplicates create confusion about which entry is109 canonical.110- **Using Artifact for ephemeral build outputs.** Not every build111 artifact needs a catalog entry. Register the ones that matter for112 the release, for compliance, or for future reference. Registering113 every intermediate build output creates noise.114- **Forgetting `produced_by`.** Linking the artifact back to the115 WorkItem or Process that produced it is cheap and makes the116 catalog navigable. Always set it when the provenance is known.117118## Full reference119120### Full field list121122See `src/context/schemas/artifact.yaml` for the authoritative schema.123124| Field | Required | Description |125|---------------|----------|-------------------------------------------------------|126| `name` | yes | Human-readable name |127| `kind` | yes | Subtype (see table above) |128| `location` | no* | Path, URL, or storage key (* required for pointers) |129| `format` | no | File format or MIME type (e.g. `pdf`, `image/png`) |130| `version` | no | Version identifier for the artifact |131| `checksum` | no | Hash for integrity verification |132| `owner` | no | Actor ID responsible for the artifact |133| `produced_by` | no | Entity ID (WorkItem, Process) that produced this |134| `produced_at` | no | ISO 8601 datetime when the artifact was produced |135| `tags` | no | Freeform tags for retrieval |136137### Note vs Artifact decision rule138139| State | Use |140|---------------------------------|-----------|141| Idea, half-formed thought | Note |142| In-progress document | Note or WorkItem body |143| Finished, shareable deliverable | Artifact |144| External resource to reference | Artifact (pointer) |145146### Relationship to WorkItems147148A WorkItem is the unit of work that produces an Artifact. Link the149two via `spec.produced_by` on the Artifact (pointing to the WorkItem150ID). This gives a navigable trail from deliverable back to the work151that created it.
projectious-work