diff --git a/.changeset/reference-skills-contract-first.md b/.changeset/reference-skills-contract-first.md new file mode 100644 index 0000000..0960dde --- /dev/null +++ b/.changeset/reference-skills-contract-first.md @@ -0,0 +1,4 @@ +--- +"github-agent-workflow": patch +--- +`agent-workflow-protocol` and `pipeline-guide` now open with `## Contract` (`kind: reference`), like every other skill, instead of carrying it near the end. The protocol's **Inputs** names both input forms (free text and key-value pairs) and says each is none. diff --git a/skills/meta/agent-workflow-protocol/SKILL.md b/skills/meta/agent-workflow-protocol/SKILL.md index 6ac3837..d87a056 100644 --- a/skills/meta/agent-workflow-protocol/SKILL.md +++ b/skills/meta/agent-workflow-protocol/SKILL.md @@ -7,6 +7,14 @@ description: Shared rules for the GitHub issue-to-merge agent workflow (group an Shared by every skill in this package. Each of them points here. Read this file once per run, then open the reference files it names only when a step tells you to. For which skill to run, see `pipeline-guide`. +## Contract + +Reference material, never run, so it has no effects to check. See **Contracts** below. + +```yaml +kind: reference +``` + ## Contracts Every skill opens with a `## Contract`: one YAML block that says what the skill is as a function. The utility skills that have none yet are listed in `CONTRACT_PENDING` in the validator, and that list only shrinks. **Process** says *how*. Where the two disagree, the contract wins, and `npm run validate` checks the parts it can. A skill is evaluated against its contract: give it a state of the world and inputs, then check what it returned and what it wrote. @@ -220,17 +228,11 @@ Hidden HTML comments make state readable without parsing prose. Append them as t | `client_guidance_files`, `item_labels N issue\|pr` | the repository's agent-facing files on the default branch (one path per line, plus `repo_guidance`), and each label on the item as `name: description`. See `references/client-guidance.md` | | `log_issue`, `log_run FILE`, `log_status`, `read_logs DAYS` | see `references/log.md` | -## Contract - -Reference material, never run, so it has no effects to check. See **Contracts** above. - -```yaml -kind: reference -``` - ## Inputs -This skill is reference material: it is never run, so it takes **no inputs** of its own. Every skill that does run names its own in its own **`## Inputs`** section, and the settings they share are in **Defaults** above. +**Free text.** None. This skill is reference material: it is never run, so it takes no inputs of its own. Every skill that does run names its own in its own **`## Inputs`** section, and the settings they share are in **Defaults** above. + +**Key-value pairs.** None. **Implicit dependencies.** None of its own. `scripts/lib.sh` needs `gh`, `jq` and Node.js. diff --git a/skills/meta/pipeline-guide/SKILL.md b/skills/meta/pipeline-guide/SKILL.md index ed47ccb..f6c0483 100644 --- a/skills/meta/pipeline-guide/SKILL.md +++ b/skills/meta/pipeline-guide/SKILL.md @@ -9,6 +9,14 @@ The table of contents for this package. It says which skill to look for and when Call a skill by its name through the Skill tool (or `/name` where your runner has slash commands). Skills never link to each other by path, because where a skill lives depends on how the package was installed. +## Contract + +Reference material, never run, so it has no effects to check. See **Contracts** in the protocol. + +```yaml +kind: reference +``` + ## Which skill, when | Skill | Kind | Use it when | @@ -57,14 +65,6 @@ The steps never call each other. They coordinate through labels, hidden marker c | Shepherding | Fixes failures, then the ready handoff and `agent:ready-for-review`. Lease: `agent:in-progress` | | Reviewing | Merges pinned to the reviewed commit, or the review handoff and back to `agent:needs-work`. Lease: `agent:in-progress` | -## Contract - -Reference material, never run, so it has no effects to check. See **Contracts** in the protocol. - -```yaml -kind: reference -``` - ## Inputs **Free text.** Optional. Ignored: this skill is a read-only index.