# Idmp Annotation

> IDMP annotation skill. Use it to read and write element annotations while keeping element annotations separate from event annotations.

- **Type:** Skill
- **Install:** `agentstack add skill-taosdata-agent-skills-idmp-annotation`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [taosdata](https://agentstack.voostack.com/s/taosdata)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [taosdata](https://github.com/taosdata)
- **Source:** https://github.com/taosdata/agent-skills/tree/main/plugins/idmp-plugin/skills/idmp-annotation

## Install

```sh
agentstack add skill-taosdata-agent-skills-idmp-annotation
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# annotation

**Read [`../idmp-shared/SKILL.md`](../idmp-shared/SKILL.md) first.**

## What this skill covers

- Read, create, update, and delete annotations attached to elements.
- Keep element annotations separate from event annotations, which use the `event annotations *` family.
- Use annotation IDs for follow-up changes after the initial list read.
- Use filtered rereads by `content` or time window to prove the exact note you just changed.

## Recommended shortcuts

| Shortcut | Purpose |
|----------|---------|
| `+list` | List annotations for one element, optionally filtered by content |

## Recommended reference

- [`Annotation read flows`](references/annotation-read-flows.md)

## Missing context to resolve first

| Context | Why it must be resolved before mutation |
| --- | --- |
| Annotation scope | Decide whether the note belongs to an element or an event before choosing the command family. |
| Owner element | Element annotation create needs the final `elementId`. |
| Target annotation ID | Update and delete need `annotationId`, not the element ID. |
| Verification plan | Decide how you will reread the annotation list after create, update, and delete. |

## Constrained live behaviors

- `annotation annotation create` writes element annotations only; event notes use the `event annotations *` family.
- `annotation annotation update` and `annotation annotation delete` act on `annotationId`, not on the owner element.
- Annotation writes are not complete until `annotation annotation list` reread shows the expected text or confirms deletion.
- `annotation annotation list` supports `content`, time windows, and small page sizes, so use filtered rereads before widening to the full page.
- `annotation annotation list` time-window filters expect epoch milliseconds, even though `annotation annotation update` can return a timestamp string. Convert the returned time before you feed it back into `updateTimeFrom` or `updateTimeTo`.
- Disposable debug notes should be deleted when the workflow ends so shared environments do not accumulate stale annotations.

## Operator workflow

1. Use this skill for element annotations only.
2. If the operator is discussing an event timeline, switch to `event annotations *`.
3. Read the element annotation list first and capture the `annotationId` before any update or delete.
4. `update` and `delete` operate on the annotation record, not on the element itself.
5. Re-read with a `content` filter first, then widen to the unfiltered first page if needed, to confirm the final text and timestamps.
6. When you need an `updateTime*` filter after `update`, normalize the returned timestamp to epoch milliseconds before the reread.

## Key commands

```bash
idmp-cli schema annotation.annotation.list
idmp-cli annotation annotation list --params '{"elementId":123,"current":1,"size":20}'
idmp-cli annotation annotation list --params '{"elementId":123,"content":"copilot note","current":1,"size":1}'

idmp-cli schema annotation.annotation.create
idmp-cli annotation annotation create --ack-risk --data '{...}'

idmp-cli schema annotation.annotation.update
idmp-cli annotation annotation update --ack-risk --data '{...}'

idmp-cli schema annotation.annotation.delete
idmp-cli annotation annotation delete --ack-risk --params '{"annotationId":456}'
```

## Exception paths

- The list is empty: treat that as “no annotations yet,” not as a product failure.
- Reads return 404 or permission errors: verify the `elementId` and the current user’s access level.
- Update or delete fails unexpectedly: confirm you passed `annotationId`, not `elementId`.
- The operator expected event notes: switch to `event annotations *` instead of forcing element commands.
- A write succeeds but the note still seems missing: remove filters and re-read the first page of results.
- Update succeeds but `updateTimeFrom` filtering misses the note: convert the returned update time to epoch milliseconds and retry the filtered list.

## Validation scenarios

1. List annotations for a known element with `idmp-cli annotation annotation list`.
2. Repeat the list with a content filter and small page size to isolate one known note.
3. Create a disposable annotation with `idmp-cli annotation annotation create --ack-risk`.
4. Update that annotation by `annotationId` with `idmp-cli annotation annotation update --ack-risk`.
5. Delete the same annotation by `annotationId` and confirm it no longer appears in the list.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [taosdata](https://github.com/taosdata)
- **Source:** [taosdata/agent-skills](https://github.com/taosdata/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-taosdata-agent-skills-idmp-annotation
- Seller: https://agentstack.voostack.com/s/taosdata
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.