Жұмыс циклдары

Файлдан дағды қосу

Дайын дағдыны инвентарьға қосу үшін:

aiman add skill path/to/skill.md

Егер осындай атаулы файл инвентарьда басқа мазмұнмен бұрыннан болса:

aiman add skill path/to/skill.md --overwrite    # қайта жазу
aiman add skill path/to/skill.md --name new-name  # басқа атаумен сақтау

Stdin-нен:

cat skill.md | aiman add skill -

Қосқаннан кейін өзгерісті жариялау үшін aiman push іске қосыңыз.

Файлдан MCP сервері қосу

MCP сервері конфигурациясын инвентарьға қосу үшін:

aiman add mcp path/to/server.yaml

Егер осындай атаулы файл инвентарьда басқа мазмұнмен бұрыннан болса:

aiman add mcp path/to/server.yaml --overwrite    # қайта жазу
aiman add mcp path/to/server.yaml --name new-name  # басқа атаумен сақтау

Stdin-нен:

cat server.yaml | aiman add mcp -

Кіріс файлда env блогінде value өрістері болса, AIM оларды автоматты түрде aim.local.yaml-ға жылжытады және mcp/<name>.yaml-ға жазбайды. Бұл секреттердің Git-ке түспейтінін қамтамасыз етеді.

Қосқаннан кейін өзгерісті жариялау үшін aiman push іске қосыңыз.

AI ортасынан дағдыны импорттау

Импорт тек белсенді инвентарь репозиторийіне жазады. Ол әлі қосылмаған болса, команда ағымдағы каталогта ештеңе жасамай, no active inventory repository; run 'aiman init' first қатесімен аяқталады — алдымен aiman init <url> немесе aiman switch <path> орындаңыз.

Дағды AI орталарының бірінде орнатылып қойған болса, оны тікелей импорттауға болады:

aiman import skill hello --from claude-code
aiman import skill review-code --from codex

Жазбасыз мазмұнды қарау:

aiman import skill hello --from claude-code --print

Қолдау көрсетілетін көздер: claude-code, cursor, codex.

Дағды тұтасымен көшіріледі: ортада ол қалта түрінде жатса (<name>/SKILL.md және references/, скрипттер), инвентарьға SKILL.md те, барлық анықтамалық файлдар да түседі. Бұл кезде қатынау құқықтары сақталмайды — скрипттердің орындалу биті жоғалады, қараңыз: Ақауларды жою.

Қосқаннан кейін өзгерісті жариялау үшін aiman push іске қосыңыз.

AI ортасынан MCP серверін импорттау

MCP сервері AI орталарының бірінде бұрыннан бапталған болса, оны тікелей импорттауға болады:

aiman import mcp context7 --from claude-code
aiman import mcp jira --from cursor

Жазбасыз мазмұнды қарау:

aiman import mcp context7 --from claude-code --print

Барлық үш AI ортасын нысана ретінде импорттау және орнату:

aiman import mcp context7 --from claude-code --targets all

Қолдау көрсетілетін көздер: claude-code, cursor, codex.

AIM көрсетілген ортаның тірі конфигурациясын оқиды, MCP сервер дескрипторын шығарады және env-strip қолданады: env айнымалыларының нақты мәндері aim.local.yaml-ға жазылады, инвентарьға және Git-ке тек секретсіз дескрипторлар түседі. Env айнымалыларының дескрипторлары атауы бойынша сұрыпталады, сондықтан өзгермеген серверді қайта импорттау Git-те артық диффтер бермейді.

Тек stdio серверлерін — ортаның конфигурациясында command белгіленгендерін — импорттауға болады. "type": "http", "type": "sse" немесе жалаң "url" арқылы жарияланған сервер импортталмайды: команда себебін атап, қатемен аяқталады және инвентарьға ештеңе жазбайды.

Егер инвентарьда осы атаумен сервер басқа мазмұнмен бұрыннан болса, команда қатемен аяқталады. Қайта жазу үшін --overwrite пайдаланыңыз:

aiman import mcp context7 --from claude-code --overwrite

Қосқаннан кейін өзгерісті жариялау үшін aiman push іске қосыңыз.

Жергілікті итерация: edit -> apply -> test

Жариялауға дейін өзгерісті тексергіңіз келсе aiman apply пайдаланыңыз.

$EDITOR skills/review-code.md
aiman apply

apply не жасайды:

• жергілікті skills/ мен mcp/ оқиды;
• элементтерді валидациялайды;
• жарамды элементтерді анықталған AI орталарына қолданады;
• commit жасамайды;
• remote-қа жүгінбейді;
• published_hash пен synced_hash-ті жаңартпайды.

Бұл цикл дағдылар әзірлеуге арналған: өңдеу, қолдану, AI-құралда тексеру, қайта өңдеу. AI орталарының көпшілігі дағдыларды сессия іске қосылуы кезінде оқиды — aiman apply кейін өзгерістердің тиімді болуы үшін агент сессиясын қайта іске қосыңыз.

Контекст ауыстыру: apply --loadout

Инвентарь өскен сайын әр міндетке әр дағды қажет бола бермейді. Loadout — инвентарьдың атаулы ішкі жиыны — AI орталарында тек қажетті жинақты ұстауға мүмкіндік береді.

Жинақты loadouts/<name>.yaml файлында сипаттаңыз:

# loadouts/documentation-work.yaml
name: Documentation Work
description: Құжаттамамен жұмысқа арналған дағдылар мен MCP
items:
  - skill:create-spec
  - skill:wpage
  - mcp:context7

Жоспарды қарап, қолданыңыз:

aiman apply --loadout documentation-work --dry-run
aiman apply --loadout documentation-work

Қолдану декларативті: орталар дәл loadout жинағына келтіріледі. Loadout-тан тыс инвентарь элементтері орталардан жойылады (өзгерістер құрамындағы D), инвентарьдан тыс файлдар қозғалмайды. Әрдайым --dry-run-нан бастаңыз — ол нақты не жойылатынын көрсетеді:

[dry-run] would apply loadout "Documentation Work" — 4 changes to 1 environment (claude-code):
  A skills/create-spec.md   (new in all environments)
  D skills/review-code.md   (would remove from all environments)
  M skills/wpage.md   (differs in all environments)
  A mcp/context7.yaml   (new in all environments)

Толық жинаққа оралу — қарапайым aiman apply немесе aiman sync.

Loadout басқа машиналарда қолжетімді болуы үшін оны жариялау керек — aiman push loadouts/ файлдарын тексеріп, оларды инвентарьдың қалған бөлігімен бірге жариялайды:

aiman push

Remote-ты loadout-тан шықпай жаңарту: пин

aiman sync әдепкі бойынша — толық инвентарьдың тасымалы: ол бүкіл инвентарьды қолданады және ортаны, бұған дейін apply --loadout арқылы тарылтқан болсаңыз да, қайта толық жинаққа дейін кеңейтеді. Бір реттік синхрондау үшін мұны sync → apply --loadout <name> үлгісімен айналып өтуге болады, бірақ remote жиі жаңарып тұрса, оны әр жолы қайталауға тура келеді.

Тар loadout-та ұзақ уақыт жұмыс істесеңіз — мысалы, бірнеше күн бойы тек құжаттамамен айналыссаңыз — және sync дәл осы жинақты өзі қолдануын қаласаңыз, loadout-ты пинмен бекітіңіз:

aiman apply --loadout documentation-work --pin

Пин — жаһандық конфигтегі сақталған күй, бір реттік әрекет емес: сіз оны нақты өзгертпейінше, ол CLI-дің әр іске қосылуы арасында белсенді болып қалады. Пин орнатылған кезде aiman sync толық инвентарьдың орнына орталарды бекітілген loadout жинағына декларативті түрде келтіреді — apply --loadout <name> сияқты, жинақтан тыс элементтерді жоюды қоса алғанда:

aiman sync

applying loadout "documentation-work" (pinned)
synced: 67451fc · 2 skills, 1 MCP server → 1 environment
  A skills/create-spec.md   (new in all environments)
  M skills/wpage.md   (updated in all environments)

Қазір қандай loadout бекітілгенін aiman status арқылы тексеруге болады — Pinned loadout: өрісі оның атауын немесе none мәнін көрсетеді.

Толық инвентарьға оралып, пинді бір әрекетпен алып тастау үшін:

aiman apply --default

Ештеңе қолданбай, жай ғана пинді алып тастау үшін (мысалы, келесі loadout-ты қолмен таңдағыңыз келсе):

aiman apply --unpin

Егер пин енді жоқ loadout-қа сілтесе (атауы өзгертілген, жойылған немесе switch мұндай атауы жоқ репозиторийге алып келген болса), sync толық жинаққа үнсіз оралудың орнына қатемен тоқтайды:

error: pinned loadout "documentation-work" not found in inventory

Пинді алып тастаңыз (aiman apply --unpin немесе --default) немесе loadout-ты күтілетін атаумен қалпына келтіріңіз — толығырақ Ақауларды жоюда.

aiman switch инвентарьдың басқа репозиторийіне ауысқанда пинді әрқашан сөзсіз алып тастайды — тіпті жаңа репозиторийде дәл сол атаумен loadout болса да; қажет болса, оны apply --loadout <name> --pin арқылы қайта бекітіңіз.

Пиннің бір реттік apply --loadout <name>-нен несімен ерекшеленетіні туралы толығырақ — Концепцияларда. Флагтар мен шығарудың толық сипаттамасы — CLI анықтамалығында.

Жариялау: status -> push

Жергілікті өзгеріс дайын болғанда:

aiman status
aiman push

status origin/main-ге қатысты репозиторий позициясын, AI орталарының күйін және skills/, mcp/ мен loadouts/ ішіндегі өзгерістер тізімін көрсетеді.

status — желілік команда: позицияны есептеу алдында Git fetch орындайды, сондықтан позиция ескірген жергілікті ref-ті емес, remote-тың нақты күйін береді. Fetch-ке кеткен қысқа кідіріс — күтілетін мінез-құлық. git status-тан айырмашылығы туралы — Концепцияларда.

TODO: fetch кезінде спиннер қосу

Жарияланбаған өзгерістер болғандағы шығару мысалы:

Repository:   git@github.com:you/aim-loadout.git
Position:     2 commits ahead of origin/main
Environments: needs sync (2 commits not applied)

Changes not yet published (origin/main → working tree):
  A skills/new-skill.md
  M skills/existing.md

  run aiman push to publish

push инвентарьды валидациялайды, commit жасайды және оны қашықтағы репозиторийге жібереді. Репозиторийде loadouts/ болса, loadout файлдары да тексеріледі: формат және items сілтемелерінің тұтастығы (бұзылған сілтеме жариялауды бұғаттайды). Жарияланғаннан кейін жарияланған өзгерістердің құрамын көрсетеді:

published: 96e091b · 19 skills, 1 MCP server
  M skills/review-code.md
  A mcp/jira.yaml

push --dry-run Git-ке жазбастан жариялау жоспарын көрсетеді:

aiman push --dry-run

Басқа машинаға тасымалдау: init -> sync

Жаңа машинада:

aiman init git@github.com:you/aim-loadout.git
aiman sync

sync Git fetch орындайды, тарихты тексереді, жарияланған күйді алады және оны жергілікті AI орталарына қолданады. Қолданғаннан кейін алынған өзгерістердің құрамын көрсетеді:

synced: 67451fc · 21 skills, 1 MCP server → 3 environments
  M skills/commit-message.md
  A skills/refactor-helper.md

Нәтиже жолындағы санауыштар — операция көлемі (барлығы қолданылды), ал төмендегі блок — өзгерістер құрамы. Remote-тан ештеңе келмесе, блок басылмайды.

Өзгерістерді жоғалудан қорғау

skills/, mcp/ немесе loadouts/ ішінде бақылаусыз файлдар болса, sync бұғатталмайды — олардың атауы remote-тан келетін файлдардың атауымен қақтығыспаған жағдайда. Әлі commit жасалмаған жаңа дағды немесе loadout сақталады.

Бақылаусыз файлдың атауы remote-тан келетін файлдың атауымен сәйкес келсе, sync тоқтайды және қақтығысатын файлдар тізімін шығарады:

aiman sync
# error: untracked file conflicts with remote: skills/review-code.md

Мүмкін іс-қимылдар:

• қақтығысатын файлды aiman push арқылы жариялау;
• файлды қолмен қайта атау немесе жылжыту;
• қақтығысатын файлдарды жойып, жарияланған күйді қолдану:

aiman sync --force

Назар аударыңыз: sync --force қақтығысатын файлдарды біржола жояды. Тек олардың жоғалуы қолайлы болғанда ғана пайдаланыңыз.

--force файлдарды үнсіз жоймайды: күй қолданылмас бұрын AIM не жойғанын тізімдейді:

discarded untracked files (--force):
  skills/draft.md
  mcp/local-only.yaml
synced: 67451fc · 21 skills, 1 MCP server → 3 environments

Қорғау skills/, mcp/ және loadouts/ каталогтарын қамтиды: осы каталогтардың кез келгеніндегі бақылаусыз файл не сақталады, не қақтығыстар тізіміне анық түседі.

Тарих күйлері

Fetch кейін AIM бірнеше жағдайды ажыратады:

Күй	Мінез-құлық
Жергілікті remote-қа тең	reset-сіз инвентарьды қолдану
Жергілікті remote-тан қалып жатыр	fast-forward reset және қолдану
Жергіліктіде жарияланбаған commit-тер бар	тоқтап, aiman push сұрау
Тарих айырылып кетті	тоқтап, Git-ті қолмен қалпына келтіруді сұрау

Қай команданы қашан пайдалану

Міндет	Команда
Файлдан дағды қосу	aiman add skill <file>
Файлдан MCP сервері қосу	aiman add mcp <file>
AI ортасынан дағды импорттау	aiman import skill <name> --from <env>
Жазбасыз дағды мазмұнын тексеру	aiman import skill <name> --from <env> --print
AI ортасынан MCP серверін импорттау	aiman import mcp <name> --from <env>
Жазбасыз MCP дескрипторын тексеру	aiman import mcp <name> --from <env> --print
Жариялаусыз жергілікті дағдыны тексеру	aiman apply
Инвентарьдың атаулы ішкі жиынын қолдану	aiman apply --loadout <name>
Қолданғанға дейін loadout жоспарын қарау	aiman apply --loadout <name> --dry-run
Жаңа немесе өзгертілген loadout-ты жариялау	aiman push
sync толық инвентарьдың орнына қолдануы үшін loadout-ты бекіту	aiman apply --loadout <name> --pin
Қандай loadout бекітілгенін тексеру	aiman status
Толық инвентарьға оралып, пинді алып тастау	aiman apply --default
Ештеңе қолданбай пинді алып тастау	aiman apply --unpin
Нені өзгерткенді қарау	aiman status
Дайын инвентарьды жариялау	aiman push
Жарияланған инвентарьды машинаға қолдану	aiman sync
Ортаны және конфигтерді тексеру	aiman doctor