Skip to content

Audit agent skills against authoring best practices + bump openspec to 1.3.1 - #309

Merged
RyanTheRobothead merged 6 commits into
unstablefrom
audit-agent-skills
May 13, 2026
Merged

Audit agent skills against authoring best practices + bump openspec to 1.3.1#309
RyanTheRobothead merged 6 commits into
unstablefrom
audit-agent-skills

Conversation

@RyanTheRobothead

@RyanTheRobothead RyanTheRobothead commented May 4, 2026

Copy link
Copy Markdown
Member

Summary

  • Audit pass on the project's agent skills against Anthropic's skill authoring guide. Renames galahadquality-checks with a discoverable description, surfaces code-ratchets' bundled scripts, and splits madsci-cli (440 → 278 lines) and madsci-managers (425 → 302 lines) using the progressive-disclosure reference/*.md pattern.
  • Updates the template engine's _copy_skills to copy entire skill directories (not just SKILL.md), so reference files and bundled scripts propagate to projects generated from lab/, module/, workflow/, and experiment/ templates. Refactored helper keeps within the existing C901 complexity budget.
  • Vendors quality-checks and code-ratchets directly into .agents/skills/ and .claude/skills/ and removes skills.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 old galahad name on the next sync.
  • Pins openspec@1.3.1 in devbox and re-syncs the bundled openspec skill files / opsx slash commands to that release.
  • Adds a new keepachangelog skill capturing the Keep a Changelog 1.1.0 format plus MADSci-specific conventions already in use in docs/CHANGELOG.md (**BREAKING**: prefix, bold-backticked symbol lead-ins, #### sub-headings for large feature buckets, docs/-relative cross-references). The madsci-release-audit skill now defers CHANGELOG format rules to it and focuses on cross-checking PRs against [Unreleased].

Notes

  • Three pre-existing stale references in the openspec 1.3.1 skills are tracked upstream and not addressed here: Fission-AI/OpenSpec#643 (TodoWrite name), #913 (openspec-sync-specs core-profile packaging), #920 (Task → Agent tool rename).

Test plan

  • pytest src/madsci_common/tests/test_templates/test_template_engine.py — 312/312 pass
  • ruff check and ruff format clean (pre-commit auto-applied)
  • Generate a fresh project from lab/minimal and confirm reference/*.md files land alongside SKILL.md in .agents/skills/ (verified in .scratch/e2e-skill-copy/; diff -r against bundled source returns empty for both madsci-cli/ and madsci-managers/)
  • Confirm /quality-checks (or skill auto-trigger on type-ignore phrasing) loads the renamed skill in a Claude Code session
  • Confirm keepachangelog auto-triggers on changelog-related phrasing in a Claude Code session

RyanTheRobothead and others added 3 commits May 4, 2026 12:49
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>
@github-actions

github-actions Bot commented May 4, 2026

Copy link
Copy Markdown

Coverage report

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  src/madsci_common/madsci/common/templates
  engine.py 312-313
Project Total  

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>
@RyanTheRobothead RyanTheRobothead self-assigned this May 13, 2026
@RyanTheRobothead RyanTheRobothead added documentation Improvements or additions to documentation enhancement New feature or request labels May 13, 2026
@RyanTheRobothead
RyanTheRobothead merged commit e3d197c into unstable May 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant