Audit agent skills against authoring best practices + bump openspec to 1.3.1 - #309
Merged
Conversation
Pins openspec to 1.3.1 in devbox and re-syncs the bundled openspec skill files and opsx slash commands to that release. The 1.2.0 → 1.3.1 jump rearranges .opencode/command/ → .opencode/commands/ and ships updated SKILL.md content for the four openspec workflows. Three previously identified stale references in the openspec skills remain unresolved upstream and are tracked as Fission-AI/OpenSpec issues #643 (TodoWrite tool name), #913 (openspec-sync-specs optional-skill packaging), and #920 (Task → Agent tool rename).
Audit pass against Anthropic's skill authoring guide (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). Skill content - Rename `galahad` → `quality-checks`. The "galahad" name is opaque unless you know Jonathan Lange's principle by name; the guide flags vague names as an anti-pattern. Body still credits the Galahad Principle as the source. - Rewrite `quality-checks` description with explicit trigger phrases (`# type: ignore`, `# noqa`, `as any`, `@ts-ignore`, `# pragma: no cover`, "skip/quarantine a test") so discovery matches the authoring guide's "what + when" recommendation. - Surface `code-ratchets`' bundled `ratchet.py` and `.pre-commit-config.yaml` at the top of SKILL.md so Claude copies the shipped files instead of regenerating equivalents from the inline snippets. - Split `madsci-cli` (440 → 278 lines) and `madsci-managers` (425 → 302 lines) using the guide's progressive-disclosure pattern: SKILL.md becomes a navigation index pointing at `reference/*.md` files for the long catalogs (command reference, template manifest format, per-manager notes, db handler details). Engine - `_copy_skills` now copies every file in a skill directory rather than only `SKILL.md`, so reference files and bundled scripts propagate to projects generated from `lab/`, `module/`, `workflow/`, and `experiment/` templates. Per-skill copy logic extracted to `_copy_skill_directory` to keep within the existing C901 complexity budget. Tests - Update `test_template_engine.py` skill assertions to count non-skill files structurally instead of pinning hardcoded totals that broke when skills started shipping multiple files. - Strengthen `test_bundled_skills_match_repo_skills` to walk the full skill directory tree rather than comparing only `SKILL.md`. - Add `test_skill_reference_files_copied` regression test for the multi-file copy path. - 312/312 tests pass; ruff clean. Lockfile / docs - `skills.lock.json`: rename `installName` to `quality-checks`. The `digest` field is now stale until the next sync against the upstream `luckierdodge/skills` rename, which has already landed on that repo's `main`. - `docs/guides/agent_skills.md`: refresh the skill listing for the rename and clarify what `quality-checks` enforces.
…json The two repo-level skills (`quality-checks`, `code-ratchets`) are now plain vendored files under `.agents/skills/` and `.claude/skills/`. Removing the lockfile avoids the stale `skillPath: skills/galahad` pointer and the digest-drift footgun on the next sync — we don't need to track these as managed dependencies on a personal upstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Coverage reportClick to see where and how coverage changed
This report was generated by python-coverage-comment-action |
||||||||||||||||||||||||
New `keepachangelog` skill captures the Keep a Changelog 1.1.0 format and the MADSci-specific conventions already in use in `docs/CHANGELOG.md` (BREAKING prefix, bold-backticked symbol lead-ins, sub-headings, relative links). The release-audit skill now defers CHANGELOG format rules to it and focuses on cross-checking PRs against `[Unreleased]`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
galahad→quality-checkswith a discoverable description, surfacescode-ratchets' bundled scripts, and splitsmadsci-cli(440 → 278 lines) andmadsci-managers(425 → 302 lines) using the progressive-disclosurereference/*.mdpattern._copy_skillsto copy entire skill directories (not justSKILL.md), so reference files and bundled scripts propagate to projects generated fromlab/,module/,workflow/, andexperiment/templates. Refactored helper keeps within the existing C901 complexity budget.quality-checksandcode-ratchetsdirectly into.agents/skills/and.claude/skills/and removesskills.lock.json. These were the only two skills tracked against a personal upstream (luckierdodge/skills), and tracking them as managed dependencies wasn't pulling its weight — the lockfile drifted on the rename and would have re-installed under the oldgalahadname on the next sync.openspec@1.3.1in devbox and re-syncs the bundled openspec skill files /opsxslash commands to that release.keepachangelogskill capturing the Keep a Changelog 1.1.0 format plus MADSci-specific conventions already in use indocs/CHANGELOG.md(**BREAKING**:prefix, bold-backticked symbol lead-ins,####sub-headings for large feature buckets,docs/-relative cross-references). Themadsci-release-auditskill now defers CHANGELOG format rules to it and focuses on cross-checking PRs against[Unreleased].Notes
Test plan
pytest src/madsci_common/tests/test_templates/test_template_engine.py— 312/312 passruff checkandruff formatclean (pre-commit auto-applied)lab/minimaland confirmreference/*.mdfiles land alongsideSKILL.mdin.agents/skills/(verified in.scratch/e2e-skill-copy/;diff -ragainst bundled source returns empty for bothmadsci-cli/andmadsci-managers/)/quality-checks(or skill auto-trigger on type-ignore phrasing) loads the renamed skill in a Claude Code sessionkeepachangelogauto-triggers on changelog-related phrasing in a Claude Code session