feat(skills): vendor writing-for-agents skill - #18
Merged
Conversation
Vendor mattpocock's writing-for-agents skill verbatim as the first skill brought in via the rebasing-adapted-skill machinery. - .agents/skills/writing-for-agents/: SKILL.md, SKILL-MECHANICS.md, and agents/openai.yaml copied byte-for-byte from upstream (git blob hashes match the pinned tip), with no metadata.internal flag. - ADAPTATION.md pins the attribution to the current 40-char commit SHA 4aaccb58d40559d7e3c59a029b2290ae5ba538de as a GitHub tree URL, with "## Deviations" declaring "- no current deviations". Refine the machinery so a verbatim vendor audits clean while keeping that human-readable line: a "## Deviations" section whose sole bullet is the literal "- no current deviations" is a sentinel meaning zero deviations, equivalent to an empty section, so it never reports as a stale bullet. Document the convention in skill-adaptation.py's audit help and output and in rebasing-adapted-skill/SKILL.md, and cover it with three offline tests (clean sentinel, drift-under-sentinel is still undeclared, and the sentinel collapses only when it is the sole bullet).
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
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.
Intent
Vendor mattpocock's writing-for-agents skill into .agents/skills/writing-for-agents/ as the first skill brought in via the just-landed rebasing-adapted-skill machinery (PR #17). VERBATIM: SKILL.md, SKILL-MECHANICS.md, and agents/openai.yaml are copied byte-for-byte from upstream with zero edits (git blob hashes match upstream's pinned blobs); no reformatting or improvements. Vendored skills deliberately OMIT metadata.internal: true (that flag is only for firstmate's own skills); the presence of ADAPTATION.md is the orthogonal upstream-tracked signal, so its absence of that flag is intentional, not an oversight. ADAPTATION.md was scaffolded via the machinery's 'template' path and pins the attribution to the current 40-char commit SHA 4aaccb58d40559d7e3c59a029b2290ae5ba538de as a GitHub tree URL, with '## Deviations' declaring the single line '- no current deviations'. Provenance lives only in ADAPTATION.md, never in the vendored SKILL.md.
This PR also folds in a captain-approved refinement to the rebasing-adapted-skill machinery (skill-adaptation.py), authorized specifically to resolve a conflict discovered while using it: a byte-for-byte vendor has zero real differences from base, so the required human-readable '- no current deviations' line would otherwise be flagged by audit as a STALE DEVIATION. The fix makes a '## Deviations' section whose sole bullet is the literal '- no current deviations' a recognized sentinel meaning zero deviations (equivalent to an empty section), so a verbatim vendor audits clean while keeping the readable line; it collapses ONLY when it is the section's sole bullet. The convention is documented in the audit --help epilog, echoed in audit output, and in rebasing-adapted-skill/SKILL.md, and covered by three new offline tests in tests/fm-skill-adaptation.test.sh (clean sentinel; drift-under-sentinel is still undeclared drift; sentinel collapses only as sole bullet). This is a deliberate, scoped machinery change, not accidental scope creep. validate-skill-dir and audit both pass clean on the vendored dir; fm-lint.sh (shellcheck 0.11.0) is clean.
What Changed
writing-for-agentsskill with pinned provenance and register it for agent-runtime use.- no current deviationsbullet as a zero-deviation sentinel while still detecting undeclared drift.Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ **Rebase** - passed
✅ **Review** - completed
✅ **Test** - passed
✅ **Document** - passed
✅ **Lint** - passed
✅ **Push** - passed