Инвентарь форматы

Skill Item

Жол:

skills/<name>.md

Мысал:

---
name: create-spec
description: Әзірлеуші үшін қысқаша ТЗ жазу
targets:
  - claude-code
  - cursor
---

# Role

...

Өрістер:

Өріс	Міндетті	Сипаттама
name	иә	Дағды идентификаторы; файл атымен сәйкес болуы керек
description	иә	Дағдының қысқаша сипаттамасы; ол болмаса дағды жарамсыз деп есептеледі және қолданылмайды
targets	жоқ	Дағды жеткізуін шектейтін AI орталар тізімі; төменде қараңыз

Frontmatter кейінгі Markdown денесі бос болмауы керек.

targets жеткізуді шектейді. Өріс барлық жолдарда — apply, sync, apply --loadout және pinned sync — қолдануға әсер етеді. Өріс болмаса немесе тізім бос болса, дағды анықталған барлық AI орталарына қолданылады — бұл әдепкі мінез-құлық. Тізім бос болмаса, дағды анықталған орталардың ішінен тек тізімде аталғандарына ғана орнатылады.

Бұл MCP Item-ден өзгеше, онда targets міндетті: MCP Item-де бос тізім — валидация қатесі, ал Skill Item-де — «барлық жерге қолдану». Асимметрия әдейі жасалған: өрісті міндетті ету targets-сіз тіркелген дағдылары бар қолданыстағы инвентарьларды бұзар еді.

targets-тегі орта атаулары валидацияланбайды: жазу қатесі (мысалы, claud-code) қате бермейді — дағды жай ғана ешбір ортаға түспейді.

Folder Skill

Skill Item қалта түрінде сақталуы мүмкін:

skills/<name>/SKILL.md
skills/<name>/agent-patterns.md   # қосымша анықтамалық файлдар
skills/<name>/delegation.md
skills/<name>/examples.md

SKILL.md — frontmatter мен денесі бар дағдының негізгі файлы. Қалтадағы қалған файлдар анықтамалық: оларды SKILL.md-де @mention арқылы атауға болады. Дағды орнатылған кезде бүкіл қалта AI ортасына көшіріледі.

Басымдық: skills/<name>.md және skills/<name>/SKILL.md бір мезгілде болса, жалпақ файл (<name>.md) қолданылады.

Қалталық дағды үшін name frontmatter-ден емес, директория атынан алынады; description мен SKILL.md-дегі бос емес дене жалпақ дағдыдағыдай міндетті.

Шектеу: apply --dry-run және дельта есебі тек SKILL.md хешін салыстырады. Қалтадағы анықтамалық файлдардың өзгерістері өзгерістер құрамында көрінбейді. Дәл осы себептен aiman add skill <dir> мен aiman import skill SKILL.md өзгермесе, дағдыны already identical деп есептейді — тек анықтамалық файлдардағы өзгерістер инвентарьға тасымалданбайды.

Шектеу: файлдардың қатынау құқықтары инвентарьға қосқанда да, AI ортасына орнатқанда да сақталмайды — барлық файлдар 0644 ретінде жазылады. Қалталық дағдының ішіндегі скрипттердің орындалу биті жоғалады.

MCP Item

Жол:

mcp/<name>.yaml

Мысал:

name: context7
description: MCP арқылы кітапхана құжаттамасы
command: npx
args:
  - -y
  - "@upstash/context7-mcp"
targets:
  - claude-code
  - cursor
  - codex
env:
  - name: UPSTASH_REDIS_REST_URL
    description: Upstash Redis қоймасының URL-і
    required: true
    example: https://example.upstash.io

Өрістер:

Өріс	Міндетті	Сипаттама
name	иә	MCP сервері идентификаторы
description	жоқ	Қысқаша сипаттама
command	иә	Іске қосу командасы
args	иә	Аргументтер тізімі, бос болуы мүмкін
targets	иә	AI орталар тізімі
env	иә	Env айнымалылар тізімі, бос болуы мүмкін

Env айнымалысы

Өріс	Міндетті	Сипаттама
name	иә	Айнымалы атауы
description	жоқ	Айнымалының мақсаты
required	иә	Қолданғанда мән талап ету
example	жоқ	Мән мысалы

Env айнымалыларының мәндері MCP Item-де сақталмайды. Олар жергілікті белгіленіп, aim.local.yaml-да сақталады.

Loadout Item

Жол:

loadouts/<name>.yaml

Мысал:

name: Documentation Work
description: Құжаттамамен жұмысқа арналған дағдылар мен MCP
targets:
  - claude-code
items:
  - skill:create-spec
  - skill:wpage
  - mcp:context7

Өрістер:

Өріс	Міндетті	Сипаттама
name	иә	Loadout-тың адам оқи алатын идентификаторы
description	жоқ	Жинақтың мақсаты; болмаса — ескерту
items	иә	skill:<name> немесе mcp:<name> сілтемелерінің бос емес тізімі
targets	жоқ	Loadout қолдануға рұқсат етілген AI орталарының шектеуі

Инварианттар:

• items бос бола алмайды;
• әр сілтеменің skill: немесе mcp: префиксі және бос емес атауы болады;
• әрбір skill:<name> skills/<name>.md немесе skills/<name>/SKILL.md ретінде бар;
• әрбір mcp:<name> mcp/<name>.yaml ретінде бар;
• файл атауы — name өрісінің нормаланған түрі (бос орындар → дефис, кіші регистр); сәйкессіздік — ескерту.

Формат пен сілтемелік тұтастық aiman push кезінде тексеріледі. aiman apply --loadout бірінші формат қатесінде тоқтайды; қолдану кезінде жоғалған немесе жарамсыз инвентарь элементіне сілтеме ескерту береді, элемент өткізіліп жіберіледі.

targets қиылысуы

Loadout деңгейіндегі targets — жеткізу селекторы емес, рұқсат етілген орталардың шектеуі (whitelist):

• targets көрсетілген — loadout анықталған орталардың ішінен тек аталғандарына қолданылады;
• targets көрсетілмеген — loadout деңгейінде шектеу жоқ, әр элементтің item деңгейіндегі targets-і жұмыс істейді;
• loadout деңгейі мен item деңгейіндегі targets қиылысу ретінде біріктіріледі: элемент ортаға тек екі деңгейде де рұқсат етілген жағдайда ғана қолданылады. Бұл MCP Item үшін де (targets міндетті), Skill Item үшін де (targets міндетті емес; item деңгейінде өрістің болмауы немесе бос тізім қиылысуды тарылтпайды — тек loadout деңгейіндегі шектеу жұмыс істейді) дұрыс.

Екі деңгейдегі шектеулер жою кезінде әртүрлі мінез көрсетеді. Loadout деңгейіндегі targets кесіп тастаған орта жоспарға кірмейді және мүлде өзгермейді. Жоспарда қалған орта қалаулы жинаққа тұтасымен келтіріледі — сондықтан loadout-қа кіретін, бірақ өзінің item деңгейіндегі targets тізімінде осы ортаны атамаған элемент (дағды немесе MCP сервері), сол ортада орнатылған болса, одан жойылады. Дағды үшін бұл тек declarative жолда (apply --loadout, pinned sync) орын алады: аддитивті жолдарда (sync, --loadout-сыз apply) дағды тек рұқсат етілген орталарға орнатылады және targets кейін тарылтылса да ешқашан жойылмайды.

Targets

Қолдау көрсетілетін мәндер:

• claude-code;
• cursor;
• codex.