With package skills

.agents/skills/docs-start/SKILL.md

@@ -13,7 +13,7 @@ usually all that is needed.
 ## 1. Check first, change nothing
 
 ```bash
-bash .claude/skills/docs-start/check-stack.sh
+bash .agents/skills/docs-start/check-stack.sh
 ```
 
 Run it with the Bash tool (Git Bash on Windows). It is read-only and takes

.agents/skills/docs-start/check-stack.sh

@@ -5,7 +5,7 @@
 # It prints what is missing, stale or running, then a suggested plan made of
 # Makefile targets where one exists. Run it from anywhere in the repository:
 #
-#   bash .claude/skills/docs-start/check-stack.sh
+#   bash .agents/skills/docs-start/check-stack.sh
 #
 # Works in Git Bash (Windows), Linux and macOS.
 

.gitignore

@@ -87,6 +87,7 @@ db.sqlite3
 # AI
 CLAUDE.md
 !AGENTS.md
+.claude/
 .cursor/
 .cursorrules
 .windsurfrules
@@ -94,7 +95,5 @@ CLAUDE.md
 .copilot/
 .github/copilot-instructions.md
 .playwright-mcp
-# AI Claude
-.claude/*
-!.claude/skills/
-.claude/skills/local-*/
+# Generated by `make skills` from .agents/skills
+skills-lock.json

AGENTS.md

@@ -293,7 +293,7 @@ Never record facts about the current issue, temporary bugs, line numbers, branch
 Put it in the narrowest place that fits:
 
 - **This file**: repository-wide rules and conventions that most tasks need, whatever the agent
-- **An existing Skill** for the workflow it belongs to (E2E tests, backend, review, running the stack…), when your agent setup has one. Claude Code Skills are versioned in `.claude/skills/<name>/SKILL.md`, except the `local-*` ones, which are gitignored: an edit there will not show in `git diff`, so name it in your report
+- **An existing Skill** for the workflow it belongs to (E2E tests, backend, review, running the stack…), when your agent setup has one. Skills are versioned in `.agents/skills/<name>/SKILL.md`, the one place to edit them: `.claude/` is gitignored and `make skills` regenerates `.claude/skills/` from it, so an edit there is lost and will not show in `git diff`. The same goes for the `local-*` skills, which only exist in `.claude/skills/`: name them in your report
 - **The subsystem's own documentation** (e.g. `src/yhub-server/README.md`, `documentation/`) when it is useful to humans too
 - **A new Skill** only for a substantial, repeatable workflow with no natural home, never for a single tip
 

Makefile

@@ -454,6 +454,16 @@ mails-install: ## install the mail generator
 .PHONY: mails-install
 
 # -- Misc
+SKILLS_CLI    = npx --yes skills@1.7.1
+# Agents that do not read .agents/skills and need their own copy of the skills
+SKILLS_AGENTS = claude-code augment continue goose junie kiro-cli
+SKILLS_AGENT ?= claude-code
+
+skills: ## generate the skills of an agent from .agents/skills (SKILLS_AGENT=claude-code)
+	@$(if $(filter $(SKILLS_AGENT),$(SKILLS_AGENTS)),,$(error SKILLS_AGENT must be one of: $(SKILLS_AGENTS) (got '$(SKILLS_AGENT)')))
+	$(SKILLS_CLI) add ./.agents/skills --skill '*' --agent $(SKILLS_AGENT) --copy --yes
+.PHONY: skills
+
 clean: ## restore repository state as it was freshly cloned
 	git clean -idx
 .PHONY: clean

README.md

@@ -196,7 +196,11 @@ username: impress
 password: impress
 ```
 
-Alternatively, you can start the project with the Claude `/docs-start` skill.
+Alternatively, you can start the project with the `/docs-start` agent skill.
+The skills live in `.agents/skills/`, which Codex, Cursor and other agents read
+directly. For Claude Code, run `make skills` once (and after each change to
+them) to generate `.claude/skills/`. Other agents that need their own copy
+can be targeted with `make skills SKILLS_AGENT=<agent>`.
 It checks what is already built, stale or running, then runs only the Make
 targets needed: `make bootstrap` on a first run, the rebuild of the images
 whose dependencies changed after a pull, or just `make run`.