Your repo is where the spec has to live, javadoc or markdown, because the agent goes back to it while it works and a skill file in a separate location gets read once at the start. What broke for me was treating the skill as the artefact and the spec as documentation, so the two drifted and the agent followed whichever it hit last. Now the spec is the thing I review and the skill file is just how it gets loaded. The location matters less than the habit.
Adam Lewis
Product Engineer/Architect navigating the AI revolution
Your repo is where the spec has to live, javadoc or markdown, because the agent goes back to it while it works and a skill file in a separate location gets read once at the start. What broke for me was treating the skill as the artefact and the spec as documentation, so the two drifted and the agent followed whichever it hit last. Now the spec is the thing I review and the skill file is just how it gets loaded. The location matters less than the habit.