diff --git a/.claude/skills/docs-accessibility-review/SKILL.md b/.agents/skills/docs-accessibility-review/SKILL.md similarity index 100% rename from .claude/skills/docs-accessibility-review/SKILL.md rename to .agents/skills/docs-accessibility-review/SKILL.md diff --git a/.claude/skills/docs-backend-django/SKILL.md b/.agents/skills/docs-backend-django/SKILL.md similarity index 100% rename from .claude/skills/docs-backend-django/SKILL.md rename to .agents/skills/docs-backend-django/SKILL.md diff --git a/.claude/skills/docs-create-issue/SKILL.md b/.agents/skills/docs-create-issue/SKILL.md similarity index 100% rename from .claude/skills/docs-create-issue/SKILL.md rename to .agents/skills/docs-create-issue/SKILL.md diff --git a/.claude/skills/docs-e2e-test/SKILL.md b/.agents/skills/docs-e2e-test/SKILL.md similarity index 100% rename from .claude/skills/docs-e2e-test/SKILL.md rename to .agents/skills/docs-e2e-test/SKILL.md diff --git a/.claude/skills/docs-pr-review/SKILL.md b/.agents/skills/docs-pr-review/SKILL.md similarity index 100% rename from .claude/skills/docs-pr-review/SKILL.md rename to .agents/skills/docs-pr-review/SKILL.md diff --git a/.claude/skills/docs-start/SKILL.md b/.agents/skills/docs-start/SKILL.md similarity index 99% rename from .claude/skills/docs-start/SKILL.md rename to .agents/skills/docs-start/SKILL.md index 44c04d013..37d0b2ed2 100644 --- a/.claude/skills/docs-start/SKILL.md +++ b/.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 diff --git a/.claude/skills/docs-start/check-stack.sh b/.agents/skills/docs-start/check-stack.sh similarity index 99% rename from .claude/skills/docs-start/check-stack.sh rename to .agents/skills/docs-start/check-stack.sh index 964902dd9..bc62b5839 100644 --- a/.claude/skills/docs-start/check-stack.sh +++ b/.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. diff --git a/.gitignore b/.gitignore index 8911ab54d..eaf48cb7d 100644 --- a/.gitignore +++ b/.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-*/ \ No newline at end of file +# Generated by `make skills` from .agents/skills +skills-lock.json diff --git a/AGENTS.md b/AGENTS.md index 82975de45..ae6cc23f7 100644 --- a/AGENTS.md +++ b/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//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//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 diff --git a/Makefile b/Makefile index 9f3038c21..f9869ef62 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 32a7dc9a1..39d29e5f2 100644 --- a/README.md +++ b/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=`. 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`.