Repository navigation
feat(skills): adopt iii-skill-check render pipeline + per-worker docs/ - #109
Merged
Merged
Conversation
Wire the workers repo into the iii-hq/skills-and-validation render + verify pipeline, then refactor the seven workers that already shipped a skill.md (auth-credentials, llm-budget, models-catalog, session-tree, shell, subagent, turn-orchestrator) onto the canonical docs/ layout. Each refactored worker now sources its README.md, skill.md, and skills/*.md from docs/intro.md, docs/quickstart.md, docs/companions.md, docs/leaves/*.md, iii.worker.yaml, and config.yaml, with rendering and verification handled by iii-skill-render and iii-skill-check. Repo wiring: - .skill-check.yaml — schema v1, anthropic AI provider, claude-opus-4-7 - .github/workflows/skill-check.yml — runs on PR + push to main, uses iii-hq/skills-and-validation@v0.1 with write: true so drift is auto-rendered and committed back to the PR branch - .gitignore — drop blanket `docs` and `config.yaml` ignores so each worker can keep its source partials and runtime config in tree Per-worker: - All 7 pass `iii-skill-check verify --layers structure,vale` clean - shell/ and turn-orchestrator/ gained ARCHITECTURE.md to preserve the threat-model, payload tables, CLI flags, streaming wire shapes, and agent::events contract that don't fit the canonical README slots - shell/skills/fs/<leaf>.md flattened to shell/skills/<leaf>.md to match the renderer's flat leaf layout Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Important Review skippedToo many files! This PR contains 152 files, which is 2 over the limit of 150. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (152)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
skill-check0 verified, 1 skipped (no docs/).
Three for three. Nicely done. |
anthonyiscoding
added a commit
that referenced
this pull request
May 9, 2026
The composite action installs its binaries + bundled rules into $GITHUB_WORKSPACE/.skill-check/ and then the auto-fix commit step staged every dirty path in the workspace, including the install directory itself. That landed 4.6 MB of binaries plus the rules snapshot into the PR via the github-actions[bot] commit. Untrack the directory and add it to .gitignore so subsequent action runs cannot re-commit it. The action's auto-commit narrowing is a separate upstream concern in iii-hq/skills-and-validation; flagged in PR #109. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
anthonyiscoding
added a commit
that referenced
this pull request
May 9, 2026
The composite action installs its binaries + bundled rules into $GITHUB_WORKSPACE/.skill-check/ and then the auto-fix commit step staged every dirty path in the workspace, including the install directory itself. That landed 4.6 MB of binaries plus the rules snapshot into the PR via the github-actions[bot] commit. Untrack the directory and add it to .gitignore so subsequent action runs cannot re-commit it. The action's auto-commit narrowing is a separate upstream concern in iii-hq/skills-and-validation; flagged in PR #109. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
anthonyiscoding
force-pushed
the
add/skills-rendering-and-validation
branch
from
May 9, 2026 19:42
cb1201a to
3504897
Compare
The composite action installs its binaries and bundled rules into $WORKSPACE/.skill-check/ when running on PRs. Without this ignore the auto-fix step's commit-back stages the entire install directory. Keep the install dir out of git so CI runs cannot accidentally land binaries or vendored rules in this repo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The default `*/iii.worker.yaml` glob runs the renderer against every worker. The 20 workers that have not been migrated to the canonical docs/ layout have no docs/intro.md and the action fails immediately on them. Pin the glob to the 7 migrated workers; expand as each remaining worker migrates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
anthonyiscoding
force-pushed
the
add/skills-rendering-and-validation
branch
from
May 9, 2026 19:45
3504897 to
b36a3ad
Compare
anthonyiscoding
added a commit
to iii-hq/skills-and-validation
that referenced
this pull request
May 9, 2026
…-set A consumer PR (iii-hq/workers#109) shipped 4.6 MB of bundled binaries because the action installed iii-skill-{check,render} into \$GITHUB_WORKSPACE/.skill-check and the auto-commit step did \`git add -A\` — sweeping the install dir into the bot's "auto-render worker docs" commit alongside the actual rendered output. Two layered fixes: 1. Move the install dir to \$RUNNER_TEMP/skill-check so it can never appear in \`git status\` regardless of how the add-set is shaped. Updated all four references (download dest, render binary path, verify INSTALL_DIR env, ci-install.sh argument) to use runner.temp. 2. Tighten the auto-commit add-set: instead of \`git add -A\`, iterate the workers-glob and stage exactly the rendered artifacts — \`<dir>/README.md\`, \`<dir>/skill.md\`, and \`<dir>/skills/\` (the last with -A so stale-leaf cleanup deletions are also staged). Defense-in-depth so any future workspace pollution can't slip into bot commits either. If the scoped add finds nothing staged, the step exits clean instead of producing an empty commit. Drift detection was also rescoped to those same paths so unrelated untracked files in the consumer's workspace don't trigger the auto-commit step on \`drift=present\`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- auth-credentials/docs/leaves/get_token.md: remove a third "use case"
bullet ("One-off debugging where a stored credential needs to be
inspected directly") that did not appear in the pre-migration
skill leaf or source.
- session-tree/docs/leaves/append.md: drop the speculative claim that
omitting parent_id "creates a parent-less node and breaks
session-tree::messages reconstruction"; restore the original phrasing
about supplying the previous entry_id.
Audit of the other five migrated workers (llm-budget, models-catalog,
shell, subagent, turn-orchestrator) found no invented content.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
skill-check — worker6 verified, 20 skipped (no docs/).
Three for three. Nicely done. |
The brace-expansion glob `{auth-credentials,...}/iii.worker.yaml` was
treated as a literal directory name (the runner's `find` did not expand
braces), so the action skipped every worker with "no docs/ partials
yet". The v0.2 action already skips workers without `docs/` cleanly, so
the default `*/iii.worker.yaml` glob is the right choice — unmigrated
workers fall through as `skipped (no docs/)` rather than failing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The skills/* and skill.md files now begin with the iii-skill-render
generated banner — a single-line HTML comment — so the existing
`well_formed` check failed at "skill must start with an H1". Strip
single-line HTML comments in memory before the H1 check; the rendered
files themselves are not modified.
Canonical leaves go directly from the topical H1 to `## When to use`
with no summary paragraph in between. Gate the "summary not heading"
check on a `require_summary` flag and call it `false` for sub-skills
while keeping it `true` for the router skill (which still has the
intro.md paragraph after its H1).
Update shell/src/lib.rs include_str! paths to the flat skills/<leaf>.md
layout the renderer produces; the path-style iii://skills ids
("shell/fs/ls", …) are preserved.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Apply the suggested form `!(t.is_empty() || t.starts_with("<!--") && t.ends_with("-->"))`
across all six worker test files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…and-validation # Conflicts: # approval-gate/config.yaml # approval-gate/docs/companions.md # approval-gate/docs/intro.md # approval-gate/docs/leaves/start.md # approval-gate/docs/quickstart.md # approval-gate/tests/skill.rs # subagent/README.md # subagent/skill.md # subagent/skills/start.md
anthonyiscoding
added a commit
to iii-hq/skills-and-validation
that referenced
this pull request
May 11, 2026
Workers like \`harness\` ship an \`iii.worker.yaml\` + a \`docs/\` dir that holds skill bundles or hand-authored notes rather than the renderer's partials. The action's existing \`[ -d "\$dir/docs" ] || continue\` skip gate didn't catch them — \`docs/\` exists, just without \`docs/intro.md\` — so the renderer was invoked and failed loudly with \`Error: reading <worker>/docs/intro.md\`. \`docs/intro.md\` is the minimum required partial; a worker missing it isn't using the renderer pattern. Move the skip gate from "no docs/ dir" to "no docs/intro.md" so opted-out workers don't break CI. Symptom: iii-hq/workers#109's run on v0.2.4 failed at the harness worker. The seven workers that DO carry docs/intro.md rendered and verified cleanly; only harness needed the action to back off. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
anthonyiscoding
marked this pull request as ready for review
May 11, 2026 15:01
sergiofilhowz
approved these changes
May 11, 2026
4 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
iii-hq/skills-and-validationrender + verify pipeline (.skill-check.yaml+.github/workflows/skill-check.yml).skill.md(auth-credentials,llm-budget,models-catalog,session-tree,shell,subagent,turn-orchestrator) onto the canonicaldocs/layout, mining the pre-migrationskill.mdandskills/*.mdfor content.README.md,skill.md, andskills/*.mdfromdocs/intro.md,docs/quickstart.md,docs/companions.md,docs/leaves/*.md,iii.worker.yaml, andconfig.yaml— rendering and verification handled byiii-skill-renderandiii-skill-check.Repo wiring
.skill-check.yaml— schema v1, anthropic AI provider,claude-opus-4-7(v1 still supported by v0.2 of the action; implicitlymode: worker)..github/workflows/skill-check.yml— runs on PR + push to main, usesiii-hq/skills-and-validation@v0.2withwrite: true. The defaultworkers-glob(*/iii.worker.yaml) is fine: the v0.2 action treats unmigrated workers (nodocs/) asskipped (no docs/)rather than failing..gitignore— drop the blanketdocsandconfig.yamlignores so each worker keeps its source partials and runtime config in tree; ignore.skill-check/so the action's install directory cannot be auto-committed back.Per-worker
iii-skill-check verify --layers structure,vale,aiclean.shell/ARCHITECTURE.mdandturn-orchestrator/ARCHITECTURE.mdpreserve threat-model, full payload tables, CLI flags, streaming wire shapes, and theagent::eventscontract that don't fit canonical README slots.shell/skills/fs/<leaf>.mdflattened toshell/skills/<leaf>.mdto match the renderer's flat leaf layout.Content audit
After an initial draft, every claim in
docs/intro.md,docs/quickstart.md,docs/companions.md,docs/leaves/*.md, andconfig.yamlfor the 7 workers was audited against the pre-migrationskill.md/skills/*.md, source code, and originalREADME.md. Two minor invented additions were dropped:auth-credentials/docs/leaves/get_token.md— removed an extraneous "use case" bullet.session-tree/docs/leaves/append.md— removed a speculative claim aboutsession-tree::messagesreconstruction breaking whenparent_idis omitted.All other content is grounded in pre-migration docs or source.
Follow-up
docs/layout:acp,approval-gate,harness,hook-fanout,iii-database,iii-lsp,image-resize,mcp,oauth-anthropic,oauth-openai-codex,policy-denylist,proof,provider-anthropic,provider-openai,provider-router,session-inbox,skills,storage,todo-worker,todo-worker-python.harness/docs/already exists but holds non-canonical files (iii-skill.md,sandbox-skill.md) — those will need to move or be renamed when harness migrates. No workflow change is needed as each worker migrates; the action picks new ones up on the next run.iii-hq/skills-and-validation's composite action installed binaries to\$WORKSPACE/.skill-check/and its auto-fix commit step did not restrict the add-set to rendered worker artifacts. Earlier in this PR's history a bot commit shipped 4.6 MB of binaries before that was caught and.skill-check/was added to.gitignore.Test plan
iii-skill-check verify <worker> --layers structure,valeclean for all 7.iii-skill-check verify <worker> --layers aiclean for all 7.skill.md/skills/*.mdand source.skill-checkjob is green on this PR (now that the brokenworkers-globoverride is removed).🤖 Generated with Claude Code