refactor: move agent config to cross-harness formats (AGENTS.md + .skills/) - #274
Merged
Merged
Conversation
Plan to move agent configuration out of .cursor/ into open formats: rules become a root AGENTS.md (agents.md), skills move to a neutral .skills/ directory per the Agent Skills specification, with committed symlinks so both Claude Code and Cursor discover them. .cursor/plans/ is retained as-is with a deprecation README. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z
williscool
commented
Sep 20, 2026
Per PR review: a bare link to the environment doc is too easy to skip. AGENTS.md gets a short Development Environment section naming the dual-filesystem setup, sync delay, and Windows-only instrumentation tests, pointing at the full doc for detail. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z
Rules become a root AGENTS.md (agents.md format); skills move to a harness-neutral .skills/ directory per the Agent Skills specification, with committed symlinks so both Claude Code and Cursor discover them. - .cursor/rules/main-rules.mdc -> AGENTS.md (frontmatter dropped, body preserved verbatim; adds Agent Configuration, Development Environment and Planning sections) - .cursor/rules/wsl-unison-setup.mdc -> docs/build/wsl_unison_environment.md (alwaysApply:false reference material belongs in the docs tree) - .cursor/skills/* -> .skills/*, with .claude/skills and .cursor/skills as symlinks - plan-making templates -> assets/ per spec convention - github-pr-comments: close unterminated code fence - .cursor/plans/ retained with a deprecation README Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z
A misconfigured or mistimed sync can destroy work in ways that are hard to restore and may require a machine restart, so this is a standing rule rather than a judgment call. - AGENTS.md: dedicated section prohibiting agent-initiated unison runs - docs/build/wsl_unison_environment.md: warning at the point of use - plan: Phase 3 round-trip verification is now explicitly user-run only Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z
williscool
changed the title
Code Coverage Report
|
📊 Code Coverage Summary
|
📊 Code Coverage Summary
|
📊 Code Coverage Summary
|
📊 Code Coverage Summary
|
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
1 participant
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.
Overview
Moves agent configuration out of
.cursor/into open, cross-harness formats. Rules become a rootAGENTS.md(agents.md); skills move to a harness-neutral.skills/directory per the Agent Skills specification.Plan:
docs/dev_todo/cross_harness_agent_config.mdChanges
.cursor/rules/main-rules.mdcAGENTS.mdat repo root — frontmatter dropped, rule body preserved byte-for-byte (verified by diff).cursor/rules/wsl-unison-setup.mdcdocs/build/wsl_unison_environment.md— it'salwaysApply: falsereference material, not a standing rule.cursor/skills/*.skills/*, with.claude/skillsand.cursor/skillsas committed symlinks.cursor/plans/*.plan.mdREADME.mdmarking the directory deprecatedAGENTS.mdadds three sections on top of the ported rules: Agent Configuration (where skills/docs live), Development Environment, and Planning.Notes
Skill discovery isn't standardized. The Agent Skills spec defines the SKILL.md format, not the directory agents scan — Claude Code reads
.claude/skills/, Cursor reads.cursor/skills/, and a bare.skills/is discovered by neither. Hence canonical content in.skills/plus symlinks: Cursor keeps working unchanged, Claude Code gains discovery it didn't have (no.claude/existed before).The skills were already spec-compliant on required frontmatter. Two fixes rode along:
plan-makingtemplates moved toassets/per convention, andgithub-pr-comments/SKILL.mdhad an unterminated code fence (file ended mid-GraphQL-block).Development Environment is called out inline, not just linked (per review) — dual-filesystem setup, ~15s sync delay, Windows-only instrumentation tests.
New standing rule: agents must never run
unisonwithout explicit permission. A misconfigured sync can destroy work irrecoverably and may require a machine restart. Documented inAGENTS.mdand at the point of use in the env doc.Verification
120000; fresh clone reproduces them and all four skill files read through both.claude/skills/and.cursor/skills/namematches parent directory for both skillsassets/templates,AGENTS.md→ docs, deprecation README → skill).cursor/rulesor.cursor/skillsreferencesNot verified, and intentionally left to you: the Unison round-trip. Propagating this requires Unison to delete
.cursor/skillsas a directory and recreate it as a symlink; the profile sets neitherlinksnorfollow, and the repo had no tracked symlinks before. Worth confirming both arrive as symlinks on your next sync. Fallback if not:.skills/alone withAGENTS.mdpointing at it, costing auto-discovery. No application code is affected either way.🤖 Generated with Claude Code
https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z