Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skillctrl/lock.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"acceptedHashes": {
"skillctrl": "7c4e07ebe7af33683bce91e381fcfb494e86bdbb"
"skillctrl": "4053fa0c4f206733210723bf5fa31d85adcf1c5d"
},
"upstreams": {
"skillctrl": {
Expand Down
5 changes: 3 additions & 2 deletions .agents/skills/skillctrl/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,11 +97,12 @@ Important behavior:
- `update` without names refreshes all registered skills; use it only when the
requested scope is all skills. An unchanged upstream original is skipped.
- A changed single-input original is three-way merged into the local skill,
using the previous original stored in `.agents/skillctrl/originals/<name>/`.
using the registered tree hash to recover the previous original from repository
Git objects or upstream history, for every adapter without a recorded commit.
Local edits survive unless the upstream changed the same lines. Each changed
skill appears in the JSON `updates` with `merged`, `conflicted` (resolve the
reported diff3 regions), or `replaced` (no previous original was available:
re-adapt from the intent once). Commit the stored original with the skill;
re-adapt from the intent once). Legacy base snapshots are ignored;
`record` refuses content that still has conflict markers.
- `remove` deletes the skill, its saved intent document, and registrations.
- `--dry-run` checks basic arguments and reports command metadata without making
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/skillctrl/evals/evals.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
},
{
"id": 2,
"prompt": "I ran skillctrl update browser from /tmp/project. It succeeded and reported {\"repo\":\"/tmp/project\",\"skills\":[\"browser\"],\"updates\":[{\"name\":\"browser\",\"path\":\".agents/skills/browser\",\"layout\":\"single\",\"status\":\"conflicted\",\"base\":\"snapshot\",\"original\":\".agents/skillctrl/originals/browser\",\"conflicts\":[{\"path\":\"SKILL.md\",\"kind\":\"content\",\"lines\":[[12,20]]}]}]}. check reports local.lock_changed=true. What should I inspect and do next? This is a read-only planning exercise; do not execute commands or change files.",
"prompt": "I ran skillctrl update browser from /tmp/project. It succeeded and reported {\"repo\":\"/tmp/project\",\"skills\":[\"browser\"],\"updates\":[{\"name\":\"browser\",\"path\":\".agents/skills/browser\",\"layout\":\"single\",\"status\":\"conflicted\",\"base\":\"upstream-history\",\"conflicts\":[{\"path\":\"SKILL.md\",\"kind\":\"content\",\"lines\":[[12,20]]}]}]}. check reports local.lock_changed=true. What should I inspect and do next? This is a read-only planning exercise; do not execute commands or change files.",
"expected_output": "Starts from the update report, the skill diff and the saved intent in the selected repository, resolves the reported conflict by direct verified editing, and uses record only after the content meets the intent.",
"files": [],
"expectations": [
Expand Down
13 changes: 7 additions & 6 deletions .agents/skills/skillctrl/references/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,12 +111,14 @@ give it the whole patch of every skill:
| `status` | Give the agent | Agent task |
| --- | --- | --- |
| `merged` | Intent and `git diff -- <path>` | Check the applied upstream change against the intent; edit only where it violates the intent |
| `conflicted` | Intent, `conflicts`, and `git diff -- <path>` | Resolve each reported region following the intent; for binary or deleted-file conflicts, compare with the new original under `original` |
| `replaced` | Intent and the whole skill directory | No previous original was available: adapt the new original from the intent once; later updates merge |
| `conflicted` | Intent, `conflicts`, and `git diff -- <path>` | Resolve each reported region following the intent; for binary or deleted-file conflicts, inspect the new original at the registered upstream source and skill path |
| `replaced` | Intent and the whole skill directory | Base recovery failed (see `reason`): inspect lost local-only files and adapt the replacement; later updates can merge if the tree remains reachable |
| `refreshed` | Integration intent, root `SKILL.md`, and `git diff` of each changed input path | Check that routing still fits the refreshed originals |

`path` is the skill directory and `original` its stored new original; the diff
of `original` is the pure upstream difference when the merged diff is unclear.
`path` is the skill directory; `changes` lists upstream file changes. Base trees
come from repository objects, upstream history, or a recorded Git source commit.
History recovery works with every adapter and needs no recorded commit.
Updates require upstream access; PR `check` remains offline.
Read beyond the diff only when needed: follow resources from changed text, and
check whole-skill intent requirements with a search over the skill. Before
recording, confirm that no conflict markers remain, for example with
Expand All @@ -126,8 +128,7 @@ intent-free skills. Run the hash gate and repository checks before publication.
If adaptation is unresolved, report the problem and leave it unaccepted.

When there are verified changes, open a draft PR containing the skill changes,
stored originals under `.agents/skillctrl/originals/`, registrations, accepted
hashes, and evidence. When there are no changes, finish without creating a PR.
registrations, accepted hashes, and evidence. When there are no changes, finish without creating a PR.
The PR uses the ordinary PR check above; a new upstream release alone never
makes an unrelated PR fail.

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
skillctrl lets you install agent skills and customize them for your project.
Shorten instructions, add your own checks, or combine skills into one workflow.

It keeps upstream originals and the intent behind your edits so your existing
It tracks upstream originals and the intent behind your edits so your existing
agent can preserve those customizations when adapting upstream updates.

https://github.com/user-attachments/assets/48394b56-6be3-47a5-b21a-4e3b3c851d72
Expand Down
3 changes: 3 additions & 0 deletions docs/adr/2026-10-15-three-way-update.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Merge upstream changes into adapted skills with a stored base

Status: superseded for base storage and resolution by [2026-10-23: Recover three-way bases from upstream tree history](2026-10-23-base-from-upstream-tree.md). The snapshot procedures below are historical, not current instructions.


- Status: Accepted
- Date: 2026-10-15

Expand Down
96 changes: 96 additions & 0 deletions docs/adr/2026-10-23-base-from-upstream-tree.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Recover three-way bases from upstream tree history

Status: accepted. Supersedes [2026-10-15: Three-way update](2026-10-15-three-way-update.md)
for base storage and resolution. File reconciliation and merged-reference behavior
remain unchanged.

## Context

Native skills and gh registrations record an original skill tree hash but no
source commit. A missing local base previously forced replacement even when the
registered tree was reachable in upstream history. Replacement deletes local-only
files, including tests. Keeping a second complete original in the consumer
repository also duplicates content and enlarges checkouts and review diffs.

The earlier ADR considered fetching a recorded commit, but did not consider
looking up the recorded tree directly after fetching upstream history.

## Decision

Resolve the previous original only for a changed single-input update, in order:

1. Read the registered `skillFolderHash` from the consumer's Git objects.
2. Fetch upstream history into disposable bare storage with `--filter=blob:none`,
then read that tree identifier directly. This works with skills, gh, and git
acquisition adapters and does not require a recorded commit or skill path.
3. Retain the direct Git adapter's recorded source commit fetch as a last resort,
including its commit/path identity check.

Verify recovered files against the registered tree hash before reconciliation.
Use the existing source validator: `sourceUrl`, when present, must identify the
same GitHub repository as `source`; otherwise derive the URL from `source`.
Do not broaden supported protocols, execute upstream scripts, or change the
chosen acquisition adapter. A missing tree/hash retains the reasoned `replaced`
fallback, which can delete
local-only files and requires review before acceptance. Fetch failures, invalid
source URLs, unreadable trees, or verification errors abort preparation if the
recorded-commit fallback cannot recover a verified base. A transient failure must
not cause destructive replacement.

Fetch all advertised branch and tag histories without a depth limit. A default
branch fetch can miss a tree retained on another branch or release tag; shallow
fetches can miss arbitrarily old imports. Private pull-request refs and unreachable
objects are outside the search. Fetch commits and trees first; a promisor remote
loads blobs only for the requested tree. Missing blob IDs are prefetched in one
batch per tree to avoid a separate network round trip for each file. Servers that ignore filtering can send
all blobs; correctness is preserved but transfer savings are not guaranteed.
Share one history fetch per validated source within preparation, and discard it
afterward. Do not add persistent caches, private refs, or history to consumer
repositories. The fresh bare repository has no inherited shallow boundary;
existing shallow acquisition clones are not reused for this step.

Do not create, refresh, read, or automatically delete
`.agents/skillctrl/originals/`. Existing copies are ignored and left byte-for-byte
untouched, even by remove or merge. Keep the legacy discovery exclusion so stale
manifests cannot become skills. After upgrading all callers, users can inspect
and manually remove the directory (`git rm -r -- .agents/skillctrl/originals`
for tracked copies). Automatic deletion would discard pending edits and would
make a routine update perform an unrelated repository cleanup. Removing files
from the current tree does not shrink existing Git history.

Merged routing skills keep their registered originals under `references/`,
including the existing numeric-layout compatibility. They are part of the skill's
content, not single-input merge bases.

JSON keeps the existing statuses and adds `base: upstream-history`; `repository`
and `upstream` continue to identify local objects and recorded-commit recovery.
The obsolete snapshot `original` path is omitted. `changes` reports upstream file
changes; conflict reports retain paths and line ranges. To resolve binary or
deletion conflicts, inspect the new original at the registered upstream source
and skill path rather than a stored local duplicate.

## Tradeoffs and alternatives

- Each changed source whose base is absent locally needs a full history fetch on
each update invocation. This costs network time and commit/tree bandwidth,
but removes duplicated originals and persistent cache lifecycle concerns.
Unchanged originals do not trigger base fetches. Explicit update already needs
upstream access; `check`, record, remove, and dry runs stay offline.
- Keeping snapshots would improve offline base availability, but preserves the
repository growth and double management the user chose to remove. No snapshot
compatibility fallback is retained.
- Fetching a tree hash directly is smaller but servers need not allow arbitrary
tree wants. Fetching advertised history provides a portable reachability path.
- A rewritten upstream can remove the only base. The recorded-commit fallback
may still recover it; otherwise replacement reports why. A network or
verification error aborts preparation if commit recovery also fails, preserving
the installed skills rather than replacing them.
- Fetching only one branch or a bounded depth is faster but silently loses valid
bases. No such optimization is included without a separate decision and tests.

## Verification

CLI tests use local Git fixture repositories through URL rewriting, without
network access. They cover commit-free skills/gh registrations, history recovery,
local-object priority, unavailable trees and rewritten history, ignored legacy
copies, local-only files, conflicts, and unchanged merged routing behavior.
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ one decision or milestone; filenames are `<date>-<slug>.md`.
| 2026-10-05 | [Consolidate upstream tracking and accepted hashes in one private lock](2026-10-05-unified-private-lock.md) |
| 2026-10-06 | [Ship v0.3.1 and announce it publicly](2026-10-06-v0-3-1-release.md) |
| 2026-10-15 | [Merge upstream changes into adapted skills with a stored base](2026-10-15-three-way-update.md) |
| 2026-10-23 | [Recover three-way bases from upstream tree history](2026-10-23-base-from-upstream-tree.md) |
5 changes: 3 additions & 2 deletions docs/ja/skills/skillctrl/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,11 +102,12 @@ native 形式の root `skills-lock.json` と、`.agents/skillctrl/lock.json` に

- 名前なしの `update` は登録済み skill をすべて更新する。
全 skill が依頼の対象である場合だけ使う。上流の原本が変わっていなければ更新を省略する。
- 単一の原本が変わると、`.agents/skillctrl/originals/<name>/` に保存した前回の原本を base に、
- 単一の原本が変わると、登録済み tree hash で repo の Git object または upstream の履歴から
復元した前回の原本を base に、
手元の skill へ 3-way merge する。upstream が同じ行を変えない限りローカルの編集は残る。
変わった skill は JSON の `updates` に `merged`、`conflicted`(報告された diff3 の箇所を解消する)、
`replaced`(前回の原本がなかったため、intent に沿って一度だけ調整し直す)のいずれかで現れる。
保存した原本は skill と一緒に commit する。`record` は衝突マーカーが残った skill ディレクトリを拒否する。
adapter や commit の記録の有無には依存しない。旧 base snapshot は参照しない。`record` は衝突マーカーが残った skill ディレクトリを拒否する。
- `remove` は skill、対応する intent ファイル、登録を削除する。
- `--dry-run` は基本的な引数を確認し、変更せずに操作の概要を表示する。
取得元の fetch・内容の確認、指定 skill が上流にあるかの確認、未コミットの編集との
Expand Down
2 changes: 1 addition & 1 deletion docs/ja/skills/skillctrl/evals/evals.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
},
{
"id": 2,
"prompt": "/tmp/project で skillctrl update browser を実行しました。成功し、{\"repo\":\"/tmp/project\",\"skills\":[\"browser\"],\"updates\":[{\"name\":\"browser\",\"path\":\".agents/skills/browser\",\"layout\":\"single\",\"status\":\"conflicted\",\"base\":\"snapshot\",\"original\":\".agents/skillctrl/originals/browser\",\"conflicts\":[{\"path\":\"SKILL.md\",\"kind\":\"content\",\"lines\":[[12,20]]}]}]} と報告されました。check は local.lock_changed=true を報告しています。次に何を確認し、何をすべきですか。これは読み取り専用の計画を立てる課題なので、コマンドを実行したりファイルを変更したりしないでください。",
"prompt": "/tmp/project で skillctrl update browser を実行しました。成功し、{\"repo\":\"/tmp/project\",\"skills\":[\"browser\"],\"updates\":[{\"name\":\"browser\",\"path\":\".agents/skills/browser\",\"layout\":\"single\",\"status\":\"conflicted\",\"base\":\"upstream-history\",\"conflicts\":[{\"path\":\"SKILL.md\",\"kind\":\"content\",\"lines\":[[12,20]]}]}]} と報告されました。check は local.lock_changed=true を報告しています。次に何を確認し、何をすべきですか。これは読み取り専用の計画を立てる課題なので、コマンドを実行したりファイルを変更したりしないでください。",
"expected_output": "選んだリポジトリで update の報告・skill の差分・保存した intent から確認を始め、報告された衝突を直接編集して解消・検証する。内容が intent を満たしてから record を使う。",
"files": [],
"expectations": [
Expand Down
13 changes: 7 additions & 6 deletions docs/ja/skills/skillctrl/references/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,21 +104,22 @@ jq -e '.updates | type == "array"' skillctrl-update.json
| `status` | agent に渡すもの | agent の作業 |
| --- | --- | --- |
| `merged` | intent と `git diff -- <path>` | 適用された upstream の変更を intent と照合し、intent に反する箇所だけ編集する |
| `conflicted` | intent・`conflicts`・`git diff -- <path>` | 報告された箇所を intent に沿って解消する。バイナリや削除の衝突は `original` の新しい原本と比べる |
| `replaced` | intent と skill のディレクトリ全体 | 旧原本がなかったため、新しい原本を intent に沿って一度だけ調整する。次回以降は merge される |
| `conflicted` | intent・`conflicts`・`git diff -- <path>` | 報告された箇所を intent に沿って解消する。バイナリや削除の衝突では、登録済み upstream の source と skill path で新しい原本を確認する |
| `replaced` | intent と skill のディレクトリ全体 | `reason` で復元失敗を確認し、消えたローカル専用ファイルと置き換え後の内容を見直す。tree が到達可能なら次回以降は merge できる |
| `refreshed` | 統合の intent・ルートの `SKILL.md`・変わった入力パスの `git diff` | 更新された原本に routing が合っているか確認する |

`path` は skill のディレクトリ、`original` は保存した新しい原本である。merge 後の差分が
分かりにくいときは、`original` の差分で upstream だけの変更を確認できる。差分以外は
`path` は skill のディレクトリ、`changes` は upstream のファイル変更を示す。
base は repo の Git object、upstream 履歴、記録済み Git source commit から探す。
履歴からの復元は全 adapter に対応し、commit の記録は不要である。
update はネットワークを必要とするが、PR の `check` はオフラインのままである。差分以外は
必要なときだけ読む。変更箇所が参照する resource をたどり、skill 全体に関わる intent の要件は
skill 内の検索で確認する。record の前に、
`git grep -n -e '^<<<<<<< local' -- .agents/skills/chosen-skill` などで衝突マーカーが
残っていないことを確認する。確認後にだけ `skillctrl record chosen-skill` を実行する。
intent がない skill は記録しない。公開前に hash の判定と repo のチェックを実行し、
調整が未解決なら問題を報告して受理しない。

確認済みの変更があれば、skill の変更・`.agents/skillctrl/originals/` に保存した原本・
登録・受理済み hash・根拠を含む draft PR を作る。
確認済みの変更があれば、skill の変更・登録・受理済み hash・根拠を含む draft PR を作る。
変更がなければ PR を作らず終了する。その PR は通常の変更チェックを通す。
upstream の新しい release だけを理由に、無関係な PR を失敗にしない。

Expand Down
Loading
Loading