skills-agent

skills-agent jest centralnym rejestrem wykonywalnych umiejętności. Skill opisuje nie tylko co trzeba osiągnąć, lecz także jak runtime lub LLM ma wykonać Doctor, Repair i Validator, jakie ma granice oraz jak udowodnić rezultat.

• doctor-agent — diagnoza i dowody, bez naprawiania systemu,
• repair-agent — plan lub kontrolowana zmiana przez pull request,
• validator-agent — niezależna walidacja diagnozy, planu i rezultatów.

Repozytorium nie zastępuje tych agentów. Stanowi skill control plane: przechowuje kontrakty, procedury i instrukcje, wybiera gotowe skille, uruchamia etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi execution planes z własną logiką domenową.

Zasady budowania kontekstu dla LLM, priorytet źródeł instrukcji i granica między deterministycznym runtime a modelem są opisane w docs/skills-and-llm.md. Polecenie skills-agent context . <skill-id> --agent repair-agent materializuje dokładny, audytowalny kontekst przekazywany wykonawcy.

Najważniejsze właściwości

• jedna, walidowana definicja task.yaml,
• katalog per zadanie i per agent: SKILLS/<id>/<agent>/...,
• sekwencja doctor → repair → validator,
• jeden wymagany correlation_id zachowany w manifeście i kontraktach wszystkich trzech etapów,
• zapis wyłącznie do jednego jawnego repozytorium produktowego; wildcardy i repozytoria sterujące są odrzucane,
• jeden wersjonowany kontrakt możliwości backendu dla lokalnego github-com i GitHub.com,
• izolowany katalog każdego uruchomienia,
• ścisłe kontrakty JSON Schema dla wyników agentów,
• planowanie harmonogramu z timezone zapisanym w zadaniu,
• domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
• uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
• deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
• brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
• opcjonalny rejestr zadań na planfile (skills-agent tickets),
• opcjonalne monitorowanie procesów na urirun (skills-agent process).

Struktura repozytorium

.
├── SKILLS/
│   └── 0001_org-repo-audit/
│       ├── task.yaml
│       ├── README.md
│       ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
│       ├── repair-agent/{README.md,run.py,input/,output/,logs/}
│       └── validator-agent/{README.md,run.py,input/,output/,logs/}
├── schemas/                 # kontrakty zadań, agentów i repo docelowych
├── src/skills_agent/          # zgodny wstecz rdzeń implementacji
├── src/skills_agent/        # kanoniczna fasada importu
├── scripts/                 # cienkie entrypointy do CI
├── templates/               # czytelne szablony dla ludzi
├── docs/                    # architektura, bezpieczeństwo i plan wdrożenia
└── .github/workflows/       # CI, orkiestrator, ręczne uruchomienie i generator NL

Pakiet zadania

task.yaml jest źródłem prawdy dla automatu. README.md zawiera kontekst dla człowieka. Każdy agent ma własny entrypoint i katalogi runtime.

SKILLS/0042_customer-mail-triage/
├── task.yaml
├── README.md
├── doctor-agent/
│   ├── README.md
│   ├── run.py
│   ├── input/
│   ├── output/
│   └── logs/
├── repair-agent/
└── validator-agent/

Status ready oznacza, że kod zadania, kontrakty i kryteria akceptacji są gotowe do uruchomienia. Generator zawsze tworzy task ze statusem todo, aby wygenerowana treść nie została wykonana bez przeglądu.

Rejestr zadań (planfile) i procesy (urirun)

skills-agent działa w oparciu o listę zadań i monitorowanie procesów, ale oba filary są od siebie oddzielone i obie zależności są opcjonalne:

• Lista zadań — planfile. Kontraktem wykonania pozostaje SKILLS/<id>/task.yaml, natomiast rejestrem/backlogiem jest store planfile. Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie task:<id>, idempotentnie), więc wybór następnego zadania korzysta z kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu. Ten sam moduł udostępnia wstrzykiwalny backend PM; pętla Subactor reużywa planfile.sync.OneDevBackend, mapuje ticket po todo-task:<task_id> i zapisuje w OneDev rezultat receipt bez bezpośredniej synchronizacji z GitHub Issues.
• Procesy — urirun. Uruchomienie zadania może działać jako proces adresowany URI agent://todo/<task>/run z trwałym rekordem (pid, log, kod wyjścia) i podglądem stanu running/exit przez urirun.host.work_runs. Domyślny izolowany runner (skills-agent run) pozostaje synchroniczny; warstwa skills-agent process dokłada uruchamianie w tle z monitoringiem.

Instalacja z warstwami opcjonalnymi:

python -m pip install -e '.[dev,planfile,urirun]'

Rejestr zadań (planfile):

skills-agent tickets sync .           # rzutuj SKILLS/*/task.yaml na bilety planfile
skills-agent tickets list . --status open
skills-agent tickets next .           # następny bilet zgodny z kontraktem runnability
skills-agent tickets status . PLF-001 in_progress

Monitorowanie procesów (urirun):

skills-agent process launch . 0001_org-repo-audit --wait   # uruchom jako proces URI
skills-agent process list .                                # stan running/exit + tail logów

Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią instalacji; rdzeń (validate, discover, run, scaffold) nie wymaga żadnej z nich. Szczegóły: docs/integrations/planfile.md, docs/integrations/urirun.md.

Uruchomienie lokalne

Wymagany jest Python 3.11+.

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
make check

Walidacja i discovery:

skills-agent validate .
skills-agent discover . --event manual
skills-agent discover . --event schedule --now 2026-07-15T00:15:00Z

Test zadania audytowego bez połączenia z GitHubem:

GITHUB_ORG=example-org \
TODO_AGENT_AUDIT_FIXTURE="$PWD/SKILLS/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
skills-agent run . 0001_org-repo-audit

Wynik pojawi się w .skills-agent-runs/<task-id>/<run-id>/ i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.

Generowanie kompletnego zadania

Generator deterministyczny nie używa modelu:

skills-agent scaffold . \
  --title "Analiza nieodebranych wiadomości klientów" \
  --description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
  --type customer-support \
  --priority high \
  --scope-level external

Można również przekazać JSON zgodny z schemas/task-spec.schema.json:

skills-agent scaffold . --spec-file task-spec.json

Workflow generate-task-from-nl.yml jest opcjonalnym front-endem: GitHub Models zamienia opis na mały JSON, a ten sam deterministyczny generator tworzy pliki i otwiera draft pull request. Odpowiedź modelu nigdy nie jest wykonywana bezpośrednio.

GitHub Actions i dostęp do organizacji

Do audytu wielu repozytoriów skonfiguruj:

• variable GITHUB_ORG,
• variable TODO_AGENT_APP_CLIENT_ID,
• secret TODO_AGENT_APP_PRIVATE_KEY,
• środowisko skills-agent-apply z wymaganymi reviewerami dla tasków pull-request.

Wbudowany GITHUB_TOKEN pozostaje wystarczający dla samego repo skills-agent. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w docs/github-app.md, a kompletna instalacja i przejście na produkcję w docs/LIVE_SYSTEM_SETUP.md.

Utworzenie kolejnej rozdzielonej tożsamości Repair/Validator przez oficjalny GitHub App Manifest flow uruchamia make github-app-install.

Standard repozytorium docelowego

Każdy projekt powinien zawierać co najmniej:

• README.md — cel, instalacja, użycie i utrzymanie,
• TODO.md — wyłącznie aktywne zadania,
• CHANGELOG.md — [Unreleased] oraz wpis bieżącej wersji,
• VERSION — pojedyncza wartość SemVer,
• AGENTS.md — wskazówki dla agentów i LLM,
• PROJECT_NOTES.md — robocze przemyślenia człowieka,
• DECISIONS.md lub ADR — trwałe decyzje,
• .github/skills-agent.yml — maszynowa konfiguracja build/test/release.

Plan bezpiecznego utworzenia brakujących plików:

skills-agent bootstrap-target /path/to/repository

Zapis, bez nadpisywania istniejących plików:

skills-agent bootstrap-target /path/to/repository --apply

Szczegółowa kolejność prac dla doctor-agent, repair-agent, validator-agent i pozostałych repozytoriów znajduje się w docs/rollout.md.

Model bezpieczeństwa

1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski ready.
3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
4. Repair-agent nie może pisać, dopóki task nie ma mutation_mode: pull-request, workflow nie otrzyma apply_changes: true, a chronione środowisko nie zostanie zatwierdzone.
5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.

Więcej: docs/security.md.

Cykl TODO / CHANGELOG / VERSION

• TODO.md pokazuje tylko aktualne działania.
• Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod [Unreleased] w CHANGELOG.md.
• Przy wydaniu [Unreleased] staje się sekcją wersji, następnie aktualizowany jest VERSION i tworzona jest nowa pusta sekcja [Unreleased].
• Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.

Canonical agent Project

Agent orchestration targets organization Project #2 Agents. The verified field and option IDs exported from GitHub are versioned in config/project-2-fields.json; Project #1 IDs are rejected by tests. Runtime configuration may override PROJECT_NUMBER, but its safe default is 2.

Cross-branch live E2E

run-task.yml accepts doctor_ref, repair_ref, validator_ref, target_repository, and validator_merge_enabled. All refs default to main. AUTO_MERGE=false is invariant; the separate merge input permits one explicit Validator merge only after final validation. Write runs require different Repair and Validator App/PAT tokens and reject missing or identical mock/live credentials before agent execution.

Versioned agent processes

Skills-agent is the source of truth for the registered contracts in SKILLS/processes/v1. Repair and Validator consume data-only process definitions for checklist rendering, branch lifecycle, release metadata, and rejection retry. Operational references: docs/GITHUB_PERMISSIONS.md, docs/DELIVERY_STRATEGIES.md, docs/BRANCH_LIFECYCLE.md, docs/REPAIR_TODO_CONTRACT.md, and docs/VALIDATOR_RUNBOOK.md.