Skip to content

feat(skills): vendor writing-for-agents skill - #18

Merged
Quidge merged 3 commits into
mainfrom
fm/vendor-writing-for-agents
Aug 6, 2026
Merged

feat(skills): vendor writing-for-agents skill#18
Quidge merged 3 commits into
mainfrom
fm/vendor-writing-for-agents

Conversation

@Quidge

@Quidge Quidge commented Aug 6, 2026

Copy link
Copy Markdown
Owner

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

  • Vendor the upstream writing-for-agents skill with pinned provenance and register it for agent-runtime use.
  • Teach adapted-skill audits to treat a sole - no current deviations bullet as a zero-deviation sentinel while still detecting undeclared drift.
  • Document and add offline test coverage for sentinel auditing behavior and near-miss cases.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed
✅ **Rebase** - passed
✅ **Review** - completed
✅ **Test** - passed
✅ **Document** - passed
✅ **Lint** - passed
✅ **Push** - passed

Quidge added 3 commits August 6, 2026 04:58
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).
@Quidge
Quidge merged commit edc8293 into main Aug 6, 2026
13 checks passed
@Quidge
Quidge deleted the fm/vendor-writing-for-agents branch August 6, 2026 06:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant