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
4 changes: 4 additions & 0 deletions .changeset/reference-skills-contract-first.md
Original file line number Diff line number Diff line change
@@ -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.
20 changes: 11 additions & 9 deletions skills/meta/agent-workflow-protocol/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions skills/meta/pipeline-guide/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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.
Expand Down
Loading