Skip to content
Skills Library
Management & product · Tool integration

create-item

/create-item

Creates an MCP work item from conversation context, anchored in the right container with a declared type and its queue notes pre-filled; use when the conversation surfaces a bug, feature idea, tech debt or observation worth tracking, or the user says: track this, log this bug, create a task for, or add this to the backlog.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Creates an MCP work item from conversation context, anchored in the right container with a declared type and its queue notes pre-filled; use when the conversation surfaces a bug, feature idea, tech debt or observation worth tracking, or the user says: track this, log this bug, create a task for, or add this to the backlog.

Arguments

/create-item [optional: brief description of what to create]
Original author description

Creates an MCP work item from conversation context, anchored in the right container with a declared type and its queue notes pre-filled; use when the conversation surfaces a bug, feature idea, tech debt or observation worth tracking, or the user says: track this, log this bug, create a task for, or add this to the backlog.

How it works

  1. Step 1 - Infer intent
  2. Step 2 - Scan containers
  3. Step 3 - Anchor the item
  4. Step 4 - Pick the type and traits
  5. Step 5 - Create
  6. Step 6 - Pre-fill queue notes
  7. Step 7 - Report
  8. From a workflow findings proposal
  9. Troubleshooting
Original SKILL.md headings · 152 lines, 1,488 words
SKILL.md preview
---
name: create-item
description: "Creates an MCP work item from conversation context, anchored in the right container with a declared type and its queue notes pre-filled; use when the conversation surfaces a bug, feature idea, tech debt or observation worth tracking, or the user says: track this, log this bug, create a task for, or add this to the backlog."
argument-hint: "[optional: brief description of what to create]"
---

# create-item - Container-Anchored Work Item Creation

Create work items from conversation context: anchor them in a category container, pick a declared `type`, and pre-fill the queue notes. Call shapes are in [`_generated/call-shapes.md`](../_generated/call-shapes.md); field semantics are in `current/docs/api-reference.md`. Ids in examples are 8-hex shorts; any id field also takes the full UUID. Read every answer through the envelope: `ok`, then `data.results[i]` (`ok` or `error`) and `data.summary {ok, failed}`. When a write element fails, the call-level `error` is only `partial_failure` (no detail, no fix): read `code`, `kind` (retry class), `detail` and `fix` from `data.results[i].error`. A read (`select`) call reports its failure in the call-level `error`.

## Step 1 - Infer intent

Take from the conversation (or `$ARGUMENTS`): title, kind (bug, feature, tech debt, observation, action item, general), priority (default medium), and scope (one item, or a feature with 2 or more distinct subtasks). If the title or kind is unclear, ask with `AskUserQuestion` and concrete options, never an open question.

## Step 2 - Scan containers

Resolve the scope from the SessionStart context: a `## Project Scope` section carries a project rootId (scopes reads and anchors); a `## Personal Scope` section carries a personal root (anchors only, reads stay unscoped). With no session context, read `project.rootId` from `.taskorchestrator/config.yaml` (a file read).

With a rootId, the category containers are the direct children of the root, which an anchored overview returns (`includeChildren` is not allowed with `anchorId`):

```to-call
{"tool": "items_read", "select": "overview", "args": {"anchorId": "9f3a1c22"}}
```

With no rootId, scan unscoped (`args` `{}`) and classify the result:

| Pattern | Classification |
|---|---|
| Depth-0 item with category-named children | Hierarchical: a project root exists |
| Category-named items at depth 0, no project root | Flat: use them directly |
| No items at all | Empty: hand off to `/task-orchestrator:init`, which creates the project root |

Create-item never creates a project root. After `init` has run, restart this skill.

## Step 3 - Anchor the item

| Item kind | Category | Signal words |
|---|---|---|
| Bug, error, crash | Bugs | bug, error, crash, broken, failure, exception |
| Feature, enhancement | Features | feature, add, implement, support, capability |
| Tech debt, refactor | Tech Debt | refactor, cleanup, debt, migrate, restructure |
| Observation, friction | Observations | slow, optimize, latency, friction, gap |
| Follow-up, reminder | Action Items | todo, follow up, remind, track |
| Unclear | best match; ask if unsure | |

Use the matching category as `parentId`. If it is missing, create it first with `items_write` `create` and a declared type (Step 4; `container` when the config lists it), then use its id. With only a personal root known, use it as the parent.

Process-global types such as `agent-observation` resolve from the server config wherever they sit (4.0 rule: per-root type, server type, per-root `default`, server `default`; see [Schema pins](../../../../current/docs/config-reference.md#schema-pins)), so an observation anchors under Observations like any other item.

## Step 4 - Pick the type and traits

`type` is required on every create. Read what the root declares:

```to-call
{"tool": "config", "op": "effective", "args": {"rootId": "9f3a1c22"}}
```

`data.types` lists the declared types and `data.traits` the declared traits (`rootId` omitted reads the server config alone). When types are declared, a create with any other type fails `schema_violation` and `data.results[i].error.detail.availableTypes` lists the valid ones; a blank type always fails. A type with a schema activates gates; one without is schema-free.

Match the context to a declared type (a bug to the bug type, a feature to the feature type, and so on). With no confident match use the `default` type when it is listed; otherwise ask via `AskUserQuestion` with the declared types as options. When the config declares no types at all, any non-blank type is accepted and the item is schema-free.

Traits are an array: `"traits": ["needs-migration-review"]`. Assign only declared traits that fit the context:

| Context signal | Trait to consider (if declared) |
|---|---|
| Database migration, ALTER TABLE | `needs-migration-review` |
| Tool parameter or response shape change | `needs-api-compat-review` |
| Plugin skill or hook behaviour change | `needs-plugin-update` |
| Auth, input validation, external data | `needs-security-review` |
| Hot path, per-request work | `needs-perf-review` |

A trait that carries an `exclusive` resource (the default mode; `advisory` is recorded only, never leased) makes the item take a lease on entering work; `advance transition start` can then fail `resource_unavailable` (transient). Mention it to the user; no action is needed here.

## Step 5 - Create

Dedup first (a tree's root only; children inherit): one unscoped search. It stays unscoped because legacy depth-0 items and items under other roots would be missed by an `ancestorId` scope.

```to-call
{"tool": "items_read", "select": "search", "args": {"query": "retry backoff", "kinds": ["item"], "limit": 5}}
```

Show close matches as one FYI line (role and short id each). The user decides; never auto-link, auto-skip or auto-cancel.

Single item (bug, observation, standalone task):

```to-call
{"tool": "items_write", "op": "create", "args": {"title": "Retry on 503", "type": "bug-fix", "priority": "high", "summary": "Client gives up on the first 503.", "tags": ["backend"], "parentId": "9f3a1c22"}}
```

Work tree (a feature with 2 or more named subtasks). `create_tree` is all-or-nothing; every child needs a `type`:

```to-call
{"tool": "items_write", "op": "create_tree", "args": {"root": {"title": "Add retry layer", "type": "feature-implementation", "priority": "medium"}, "parentId": "9f3a1c22", "children": [{"ref": "t1", "title": "Backoff policy", "type": "feature-task"}, {"ref": "t2", "title": "Retry tests", "type": "feature-task"}], "deps": [{"from": "t1", "to": "t2"}]}}
```

Default to a single item when scope is unclear. A create answers `{ok, id, version}`; a tree answers `{ok, id, version, items, deps, notes}` with `items[]` `{ref, id, depth}`.

## Step 6 - Pre-fill queue notes

A create returns no `expectedNotes`. Read the item's schema with guidance:

```to-call
{"tool": "items_read", "select": "schema", "args": {"itemId": "4b7d0e19", "fields": ["guidance"]}}
```

`data` is `{schemaFree: true}` for a schema-free item (nothing to fill). Otherwise, for each note with `required: true` and `role: "queue"`, draft the body from the conversation using that note's `guidance` (and run its `skill` if set). Write all of them in one `notes_write` call, one `upsert` element per note (and per item, when several items were created):

```to-call
{"tool": "notes_write", "op": "upsert", "args": {"itemId": "4b7d0e19", "key": "diagnosis", "role": "queue", "body": "Client treats 503 as fatal; no retry path."}}
```

If the conversation is too thin for a real body, leave the note empty rather than fabricate. A `schema_pinned_conflict` on a write means the item's pin lacks a key the current config requires: `repin` it (see Troubleshooting).

## Step 7 - Report

```
Created: <title> (<short-id>)
  Path: <container path, e.g. Features>
  Tags: <tags or none>   Traits: <traits or none>
  Notes pre-filled: <keys or none>
```

Add `  Created new container: <name> under <parent>` when a category was created.

## From a workflow findings proposal

An alternate entry for materializing findings from a `task-orchestrator:audit` run. The audit script never writes items; it returns an `audit/result-v1` result with a `proposal` (candidate rows in `proposal.items[]`) and `kept[]` (surviving findings). Use this path instead of Steps 1-3 when the input is a proposal.

1. **Table.** Show one table: id, severity, class, type, materialize and reason, candidates.
2. **Dedup.** Row `candidates` come from the unscoped Step 5 search the audit already ran; cite them. Re-search only rows with `likelyDuplicate: unknown` or rows the user added or retitled. Candidates are FYI only.
3. **Edits.** The user may flip `materialize`, reclassify a row (bug, tech-debt, agent-observation) or drop it. Apply nothing without an explicit edit.
4. **Container.** Resolve ONE category container with Steps 2-3 and have the user confirm it. Non-observation rows go under a single audit container created beneath it.
5. **Priority and type.** Priority is already mapped; do not re-derive it. Use a row's own `type`; for rows without one, pick from `config effective` `types` (Step 4).
6. **Materialize** only after explicit confirmation: one `create_tree` for the audit container plus its children under the category container (split a larger proposal across calls; later calls attach with `root.id`). `agent-observation` rows are not part of this tree: create them as separate `items_write` `create` elements tagged `agent-observation` under the Observations container.
7. **Notes.** None pre-filled from the proposal; queue notes are filled later in normal planning.
8. **Report** with Step 7's format, one line per created item.

Never automated: creating without explicit confirmation, acting on dedup candidates, or materializing a `materialize: false` row the user did not flip.

## Troubleshooting

**Wrong container.** Move the item:

```to-call
{"tool": "items_write", "op": "update", "args": {"id": "4b7d0e19", "parentId": "6e21c0aa"}}
```

**`schema_violation` on create.** Read `data.results[i].error.detail.availableTypes` (or `availableTraits`) and retry with a declared name.

**Schema read says `schemaFree: true` for a typed item.** The type resolves to no schema under the item's pin. An item keeps its pin after a config push (`items_read` `get` shows `stale: true`); `repin` adopts the push:

```to-call
{"tool": "items_write", "op": "repin", "args": {"id": "4b7d0e19"}}
```

Changing `type` or `traits` with `items_write` `update` is itself a pin point; `repin` is for a push made after the pin.

Versions

RepositoryScoreLicence
This page · jpicklyk/task-orchestrator100MIT
mojang/minecraft-creator-tools100MIT

Database snapshot: 13.11.2026 · package version 01d2701e762e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100add-item
    Use when the user says "file an issue", "log this", "track this", "add a bug", "create a task", "add to backlog", or invokes /compass-rose:add-item. Replaces /lore-development:file-issue. Creates a local issue file in .lore/work/issues/.
  • 95create-work-item
    Interactively create a well-formed work item. Use when capturing a feature, bug, task, spike, or epic as a structured work item in meta/work/.
  • 96new-work-item
    Creates and scopes a new work item in this repo's work/items/ folder. Use when asked to start, track, or plan a new piece of work, or when a request arrives in work/inbox/ that has no item yet.
  • 100defer
    Defer an out-of-scope finding to the backlog. Use when a bug, tech debt, idea, or risk is discovered but not appropriate to solve now.
  • 90tech-debt-register
    Track technical debt deliberately by framing each item as interest owed and budgeting steady paydown. Use when debt is piling up as vague complaints and you need to make it fundable work.
  • 96backlog
    Add a new feature idea to the product backlog. Use when the user wants to log a new idea, feature request, or improvement.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.