{"id":"794b9778-50f1-4b4d-8af6-a34d0c16f943","shortId":"Z2uqYU","kind":"skill","title":"data-structure-protocol","tagline":">-","description":"# Data Structure Protocol (DSP)\n\nDSP builds a dependency graph of project entities in a `.dsp/` directory. Each entity (module, function, external dependency) gets a UID, description, import list, and export index. The graph answers: what exists, why it exists, what depends on what, and who uses what.\n\n**DSP is NOT documentation for humans or AST dump.** It captures _meaning_ (purpose), _boundaries_ (imports/exports), and _reasons for connections_ (why).\n\n## Agent Prompt\n\nEmbed this context when working on a DSP-tracked project:\n\n> **This project uses DSP (Data Structure Protocol).**\n> The `.dsp/` directory is the entity graph of this project: modules, functions, dependencies, public API. It is your long-term memory of the code structure.\n>\n> **Core rules:**\n>\n> 1. **Before changing code** — find affected entities via `dsp-cli search`, `find-by-source`, or `read-toc`. Read their `description` and `imports` to understand context.\n> 2. **When creating a file/module** — call `dsp-cli create-object`. For each exported function — `create-function` (with `--owner`). Register exports via `create-shared`.\n> 3. **When adding an import** — call `dsp-cli add-import` with a brief `why`. For external dependencies — first `create-object --kind external` if the entity doesn't exist yet.\n> 4. **When removing import / export / file** — call `remove-import`, `remove-shared`, `remove-entity` respectively. Cascade cleanup is automatic.\n> 5. **When renaming/moving a file** — call `move-entity`. UID does not change.\n> 6. **Don't touch DSP** if only internal implementation changed without affecting purpose or dependencies.\n> 7. **Bootstrap** — if `.dsp/` is empty, traverse the project from root entrypoint via DFS on imports, documenting every file.\n>\n> **Key commands:**\n> ```\n> dsp-cli init\n> dsp-cli create-object <source> <purpose> [--kind external] [--toc ROOT_UID]\n> dsp-cli create-function <source> <purpose> [--owner UID] [--toc ROOT_UID]\n> dsp-cli create-shared <exporter_uid> <shared_uid> [<shared_uid> ...]\n> dsp-cli add-import <importer_uid> <imported_uid> <why> [--exporter UID]\n> dsp-cli remove-import <importer_uid> <imported_uid> [--exporter UID]\n> dsp-cli remove-shared <exporter_uid> <shared_uid>\n> dsp-cli remove-entity <uid>\n> dsp-cli move-entity <uid> <new_source>\n> dsp-cli update-description <uid> [--source S] [--purpose P] [--kind K]\n> dsp-cli get-entity <uid>\n> dsp-cli get-children <uid> [--depth N]\n> dsp-cli get-parents <uid> [--depth N]\n> dsp-cli search <query>\n> dsp-cli find-by-source <path>\n> dsp-cli read-toc [--toc ROOT_UID]\n> dsp-cli get-stats\n> ```\n\n## Using the CLI\n\nThe script is at `scripts/dsp-cli.py` relative to this skill directory.\n\n```\npython <skill-path>/scripts/dsp-cli.py [--root <project-root>] <command> [args]\n```\n\n`--root` defaults to current working directory. All paths in arguments are repo-relative.\n\n## Core Concepts\n\n- **Code = graph.** Nodes are Objects and Functions. Edges are `imports` and `shared/exports`.\n- **Identity by UID, not file path.** Path is an attribute; renames/moves don't change UID.\n- **\"Shared\" creates an entity.** If something becomes public (exported), it gets its own UID.\n- **Import tracks both \"from where\" and \"what\".** One code import may create two DSP links: to the module and to the specific shared entity.\n- **Full import coverage.** Every imported file/asset must be an Object in `.dsp` — code, images, styles, configs, everything.\n- **`why` lives next to the imported entity** in its `exports/` directory (reverse index).\n- **Start from roots.** Each root entrypoint has its own TOC file.\n- **External deps — record only.** `kind: external`, no deep dive into `node_modules`/`site-packages`/etc. But `exports index` works — shows who imports it.\n\n## UID Format\n\n- Objects: `obj-<8 hex>` (e.g., `obj-a1b2c3d4`)\n- Functions: `func-<8 hex>` (e.g., `func-7f3a9c12`)\n\nUID marker in source code — comment `@dsp <uid>` before declaration:\n\n```js\n// @dsp func-7f3a9c12\nexport function calculateTotal(items) { ... }\n```\n\n```python\n# @dsp obj-e5f6g7h8\nclass UserService:\n```\n\n## Workflows\n\n### Setting Up DSP\n\n1. Run `dsp-cli init` to create `.dsp/` directory.\n2. Identify root entrypoint(s) — `package.json` main, framework entry, etc.\n3. Run bootstrap (DFS from root). See [bootstrap.md](references/bootstrap.md).\n\n### Creating Entities (when writing new code)\n\n1. Create module: `dsp-cli create-object <path> <purpose>`\n2. Create functions: `dsp-cli create-function <path>#<symbol> <purpose> --owner <module-uid>`\n3. Register exports: `dsp-cli create-shared <module-uid> <func-uid> [<func-uid> ...]`\n4. Register imports: `dsp-cli add-import <this-uid> <imported-uid> <why> [--exporter <module-uid>]`\n5. External deps: `dsp-cli create-object <package-name> <purpose> --kind external`\n\n### Navigating the Graph (when reading/understanding code)\n\n- **Find entity by file**: `dsp-cli find-by-source <path>`\n- **Search by keyword**: `dsp-cli search <query>`\n- **Read TOC**: `dsp-cli read-toc` → get all UIDs, then `get-entity` for details\n- **Dependency tree down**: `dsp-cli get-children <uid> --depth N`\n- **Dependency tree up**: `dsp-cli get-parents <uid> --depth N`\n- **Impact analysis**: `dsp-cli get-recipients <uid>` — who depends on this entity\n- **Path between entities**: `dsp-cli get-path <from> <to>`\n\n### Updating (when modifying code)\n\n- Purpose changed: `dsp-cli update-description <uid> --purpose <new>`\n- File moved: `dsp-cli move-entity <uid> <new-path>`\n- Import reason changed: `dsp-cli update-import-why <importer> <imported> <new-why>`\n\n### Deleting (when removing code)\n\n- Import removed: `dsp-cli remove-import <importer> <imported> [--exporter UID]`\n- Export removed: `dsp-cli remove-shared <exporter> <shared>`\n- File/module deleted: `dsp-cli remove-entity <uid>` (cascading cleanup)\n\n### Diagnostics\n\n- `dsp-cli detect-cycles` — circular dependencies\n- `dsp-cli get-orphans` — unused entities\n- `dsp-cli get-stats` — project graph overview\n\n## When to Update DSP\n\n| Code Change | DSP Action |\n|---|---|\n| New file/module | `create-object` + `create-function` + `create-shared` + `add-import` |\n| New import added | `add-import` (+ `create-object --kind external` if new external dep) |\n| Import removed | `remove-import` |\n| Export added | `create-shared` (+ `create-function` if new function) |\n| Export removed | `remove-shared` |\n| File renamed/moved | `move-entity` |\n| File deleted | `remove-entity` |\n| Purpose changed | `update-description` |\n| Internal-only change | **No DSP update needed** |\n\n## References\n\n- **[Storage format](references/storage-format.md)** — `.dsp/` directory structure, file formats, TOC\n- **[Bootstrap procedure](references/bootstrap.md)** — initial project markup (DFS algorithm)\n- **[Operations reference](references/operations.md)** — detailed semantics of all operations with import examples","tags":["data","structure","protocol","k-kolomeitsev","agent-skills","calude","claude-code","code-generation","code-review","codex","codex-skills","cursor"],"capabilities":["skill","source-k-kolomeitsev","skill-data-structure-protocol","topic-agent-skills","topic-calude","topic-claude-code","topic-code-generation","topic-code-review","topic-codex","topic-codex-skills","topic-cursor","topic-cursor-ai","topic-gpt","topic-openai","topic-prompt-engineering"],"categories":["data-structure-protocol"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/k-kolomeitsev/data-structure-protocol/data-structure-protocol","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add k-kolomeitsev/data-structure-protocol","source_repo":"https://github.com/k-kolomeitsev/data-structure-protocol","install_from":"skills.sh"}},"qualityScore":"0.472","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 45 github stars · SKILL.md body (6,844 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T00:57:08.756Z","embedding":null,"createdAt":"2026-04-18T22:18:19.364Z","updatedAt":"2026-05-02T00:57:08.756Z","lastSeenAt":"2026-05-02T00:57:08.756Z","tsv":"'/etc':557 '/scripts/dsp-cli.py':417 '1':120,613,648 '2':148,623,657 '3':175,633,667 '4':207,676 '5':228,686 '6':241 '7':256 '7f3a9c12':583,597 '8':570,578 'a1b2c3d4':575 'action':878 'ad':177,895,914 'add':185,313,683,891,897 'add-import':184,312,682,890,896 'affect':125,252 'agent':72 'algorithm':969 'analysi':761 'answer':38 'api':106 'arg':419 'argument':429 'ast':59 'attribut':457 'automat':227 'becom':469 'bootstrap':257,635,962 'bootstrap.md':640 'boundari':65 'brief':189 'build':10 'calculatetot':600 'call':153,180,213,233 'captur':62 'cascad':224,843 'chang':122,240,250,461,787,805,876,940,947 'children':366,746 'circular':852 'class':607 'cleanup':225,844 'cli':130,156,183,279,283,294,305,311,319,327,333,339,345,357,363,371,379,383,390,399,405,617,653,662,672,681,691,709,719,725,743,754,764,778,790,799,808,821,831,839,848,856,864 'code':116,123,436,485,513,588,647,702,785,816,875 'command':276 'comment':589 'concept':435 'config':516 'connect':70 'context':76,147 'core':118,434 'coverag':503 'creat':150,158,165,173,196,285,296,307,464,488,620,642,649,655,658,664,674,693,882,885,888,900,916,919 'create-funct':164,295,663,884,918 'create-object':157,195,284,654,692,881,899 'create-shar':172,306,673,887,915 'current':423 'cycl':851 'data':2,5,89 'data-structure-protocol':1 'declar':592 'deep':549 'default':421 'delet':813,836,935 'dep':543,688,907 'depend':12,26,45,104,193,255,738,749,769,853 'depth':367,375,747,758 'descript':30,142,348,793,943 'detail':737,973 'detect':850 'detect-cycl':849 'dfs':269,636,968 'diagnost':845 'directori':20,94,415,425,528,622,957 'dive':550 'document':55,272 'doesn':203 'dsp':8,9,19,52,82,88,93,129,155,182,245,259,278,282,293,304,310,318,326,332,338,344,356,362,370,378,382,389,398,490,512,590,594,603,612,616,621,652,661,671,680,690,708,718,724,742,753,763,777,789,798,807,820,830,838,847,855,863,874,877,949,956 'dsp-cli':128,154,181,277,281,292,303,309,317,325,331,337,343,355,361,369,377,381,388,397,615,651,660,670,679,689,707,717,723,741,752,762,776,788,797,806,819,829,837,846,854,862 'dsp-track':81 'dump':60 'e.g':572,580 'e5f6g7h8':606 'edg':443 'emb':74 'empti':261 'entiti':16,22,97,126,202,222,236,336,342,360,466,500,524,643,704,735,772,775,802,842,861,933,938 'entri':631 'entrypoint':267,536,626 'etc':632 'everi':273,504 'everyth':517 'exampl':980 'exist':40,43,205 'export':34,162,170,211,315,323,471,527,559,598,669,685,825,827,913,924 'extern':25,192,199,288,542,547,687,696,903,906 'file':212,232,274,452,541,706,795,929,934,959 'file/asset':506 'file/module':152,835,880 'find':124,133,385,703,711 'find-by-sourc':132,384,710 'first':194 'format':567,954,960 'framework':630 'full':501 'func':577,582,596 'func-7f3a9c12':581,595 'function':24,103,163,166,297,442,576,599,659,665,886,920,923 'get':27,359,365,373,401,473,729,734,745,756,766,780,858,866 'get-children':364,744 'get-ent':358,733 'get-orphan':857 'get-par':372,755 'get-path':779 'get-recipi':765 'get-stat':400,865 'graph':13,37,98,437,699,869 'hex':571,579 'human':57 'ident':448 'identifi':624 'imag':514 'impact':760 'implement':249 'import':31,144,179,186,210,216,271,314,322,445,477,486,502,505,523,564,678,684,803,811,817,824,892,894,898,908,912,979 'imports/exports':66 'index':35,530,560 'init':280,618 'initi':965 'intern':248,945 'internal-on':944 'item':601 'js':593 'k':354 'key':275 'keyword':716 'kind':198,287,353,546,695,902 'link':491 'list':32 'live':519 'long':111 'long-term':110 'main':629 'marker':585 'markup':967 'may':487 'mean':63 'memori':113 'modifi':784 'modul':23,102,494,553,650 'move':235,341,796,801,932 'move-ent':234,340,800,931 'must':507 'n':368,376,748,759 'navig':697 'need':951 'new':646,879,893,905,922 'next':520 'node':438,552 'obj':569,574,605 'obj-a1b2c3d4':573 'obj-e5f6g7h8':604 'object':159,197,286,440,510,568,656,694,883,901 'one':484 'oper':970,977 'orphan':859 'overview':870 'owner':168,298,666 'p':352 'packag':556 'package.json':628 'parent':374,757 'path':427,453,454,773,781 'procedur':963 'project':15,84,86,101,264,868,966 'prompt':73 'protocol':4,7,91 'public':105,470 'purpos':64,253,351,786,794,939 'python':416,602 'read':138,140,392,721,727 'read-toc':137,391,726 'reading/understanding':701 'reason':68,804 'recipi':767 'record':544 'refer':952,971 'references/bootstrap.md':641,964 'references/operations.md':972 'references/storage-format.md':955 'regist':169,668,677 'relat':411,433 'remov':209,215,218,221,321,329,335,815,818,823,828,833,841,909,911,925,927,937 'remove-ent':220,334,840,936 'remove-import':214,320,822,910 'remove-shar':217,328,832,926 'renamed/moved':930 'renames/moves':458 'renaming/moving':230 'repo':432 'repo-rel':431 'respect':223 'revers':529 'root':266,290,301,395,418,420,533,535,625,638 'rule':119 'run':614,634 'script':407 'scripts/dsp-cli.py':410 'search':131,380,714,720 'see':639 'semant':974 'set':610 'share':174,219,308,330,463,499,675,834,889,917,928 'shared/exports':447 'show':562 'site':555 'site-packag':554 'skill':414 'skill-data-structure-protocol' 'someth':468 'sourc':135,349,387,587,713 'source-k-kolomeitsev' 'specif':498 'start':531 'stat':402,867 'storag':953 'structur':3,6,90,117,958 'style':515 'term':112 'toc':139,289,300,393,394,540,722,728,961 'topic-agent-skills' 'topic-calude' 'topic-claude-code' 'topic-code-generation' 'topic-code-review' 'topic-codex' 'topic-codex-skills' 'topic-cursor' 'topic-cursor-ai' 'topic-gpt' 'topic-openai' 'topic-prompt-engineering' 'touch':244 'track':83,478 'travers':262 'tree':739,750 'two':489 'uid':29,237,291,299,302,316,324,396,450,462,476,566,584,731,826 'understand':146 'unus':860 'updat':347,782,792,810,873,942,950 'update-descript':346,791,941 'update-import-whi':809 'use':50,87,403 'userservic':608 'via':127,171,268 'without':251 'work':78,424,561 'workflow':609 'write':645 'yet':206","prices":[{"id":"3bd82d52-6d82-4296-9191-90f1860053e1","listingId":"794b9778-50f1-4b4d-8af6-a34d0c16f943","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"k-kolomeitsev","category":"data-structure-protocol","install_from":"skills.sh"},"createdAt":"2026-04-18T22:18:19.364Z"}],"sources":[{"listingId":"794b9778-50f1-4b4d-8af6-a34d0c16f943","source":"github","sourceId":"k-kolomeitsev/data-structure-protocol/data-structure-protocol","sourceUrl":"https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol","isPrimary":false,"firstSeenAt":"2026-04-18T22:18:19.364Z","lastSeenAt":"2026-05-02T00:57:08.756Z"}],"details":{"listingId":"794b9778-50f1-4b4d-8af6-a34d0c16f943","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"k-kolomeitsev","slug":"data-structure-protocol","github":{"repo":"k-kolomeitsev/data-structure-protocol","stars":45,"topics":["agent-skills","ai","calude","claude-code","code-generation","code-review","codex","codex-skills","cursor","cursor-ai","gpt","openai","prompt-engineering","skills","structured-data"],"license":"apache-2.0","html_url":"https://github.com/k-kolomeitsev/data-structure-protocol","pushed_at":"2026-03-23T15:43:04Z","description":"Graph-based long-term memory skill for AI (LLM) coding agents — faster context, fewer tokens, safer refactors","skill_md_sha":"70b48f91439b66c7c5a58bb4e1e84b6307fb2658","skill_md_path":"skills/data-structure-protocol/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol"},"layout":"multi","source":"github","category":"data-structure-protocol","frontmatter":{"name":"data-structure-protocol","description":">-"},"skills_sh_url":"https://skills.sh/k-kolomeitsev/data-structure-protocol/data-structure-protocol"},"updatedAt":"2026-05-02T00:57:08.756Z"}}