From 705acc3b94662e0f4e7c0e312374cac3246842fa Mon Sep 17 00:00:00 2001 From: Gerald Fruhmann Date: Thu, 13 Aug 2026 14:04:14 +0200 Subject: [PATCH] feat: add GitHub Copilot CLI support Makes this plugin dual-compatible with Claude Code and GitHub Copilot CLI, which converged on a near-identical marketplace/plugin/skill architecture. Verified live against both tools. - meta-install: new --target claude|copilot-cli, --copilot-native, and --standalone-skills modes - skill name: frontmatter changed dev: -> dev- (Copilot CLI rejects colons in skill names; confirmed no effect on Claude Code, whose /dev: invocation comes from commands/.md) - fixed 3 files with unquoted description: values containing ": ", which broke YAML parsing under Copilot CLI's stricter parser - replaced ${CLAUDE_PLUGIN_ROOT} (Claude-only) with relative paths in 4 SKILL.md files - validate-skills.sh: new Copilot CLI compatibility checks - corrected stale skill counts (24/26 -> 27) across manifests and docs Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 13 +++ CLAUDE.md | 40 +++++++-- README.md | 30 +++++-- plugins/dev/.claude-plugin/plugin.json | 2 +- plugins/dev/commands/meta-create-skill.md | 8 +- plugins/dev/commands/meta-install.md | 5 +- plugins/dev/skills/design-api/SKILL.md | 2 +- plugins/dev/skills/design-app/SKILL.md | 4 +- plugins/dev/skills/design-cicd/SKILL.md | 2 +- plugins/dev/skills/design-data/SKILL.md | 2 +- plugins/dev/skills/design-iac/SKILL.md | 2 +- plugins/dev/skills/design-llm/SKILL.md | 2 +- plugins/dev/skills/design-migration/SKILL.md | 2 +- .../dev/skills/design-observability/SKILL.md | 2 +- plugins/dev/skills/design-public/SKILL.md | 2 +- plugins/dev/skills/design-secure/SKILL.md | 2 +- plugins/dev/skills/design-ux/SKILL.md | 2 +- plugins/dev/skills/meta-create-skill/SKILL.md | 21 ++++- plugins/dev/skills/meta-drift/SKILL.md | 4 +- plugins/dev/skills/meta-help/SKILL.md | 6 +- plugins/dev/skills/meta-install/SKILL.md | 87 +++++++++++++++---- plugins/dev/skills/meta-sync/SKILL.md | 2 +- plugins/dev/skills/review-app/SKILL.md | 14 ++- plugins/dev/skills/review-arch/SKILL.md | 2 +- plugins/dev/skills/review-llm/SKILL.md | 2 +- plugins/dev/skills/review-public/SKILL.md | 2 +- plugins/dev/skills/review-secure/SKILL.md | 2 +- plugins/dev/skills/review-ux/SKILL.md | 2 +- plugins/dev/skills/tool-a11y/SKILL.md | 2 +- plugins/dev/skills/tool-debug/SKILL.md | 2 +- plugins/dev/skills/tool-perf/SKILL.md | 2 +- plugins/dev/skills/tool-style/SKILL.md | 2 +- plugins/dev/skills/tool-test/SKILL.md | 2 +- scripts/validate-skills.sh | 55 ++++++++++++ 35 files changed, 269 insertions(+), 66 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1d84e17..4aeb9d9 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,9 +6,9 @@ { "name": "dev", "source": "./plugins/dev", - "description": "24 skills for software projects: Design (App, Secure, API, Data, Migration, UX, LLM, Observability, CI/CD, IaC), Review (App, Architecture, Security, UX, LLM), Tools (Debug, Test, Style, Accessibility, Performance), Meta. Grounded in MIT, CMU, Stanford curricula.", + "description": "27 skills for software projects: Design (App, Secure, API, Data, Migration, UX, LLM, Observability, CI/CD, IaC, Public), Review (App, Architecture, Security, UX, LLM, Public), Tools (Debug, Test, Style, Accessibility, Performance), Meta. Grounded in MIT, CMU, Stanford curricula. Works with Claude Code and GitHub Copilot CLI.", "category": "development", - "tags": ["best-practices", "security", "architecture", "llm", "accessibility", "performance", "ci-cd", "iac"] + "tags": ["best-practices", "security", "architecture", "llm", "accessibility", "performance", "ci-cd", "iac", "copilot-cli"] } ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index c745665..31b47f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ Format: [Semantic Versioning](https://semver.org). Dates: YYYY-MM-DD. ## [Unreleased] +### Added + +- GitHub Copilot CLI support: this plugin now works as a Copilot CLI plugin/marketplace as well as a Claude Code plugin, without a second manifest or generated duplicate tree +- `meta-install --target claude|copilot-cli`, plus `--copilot-native` and `--standalone-skills` modes, for installing rules/skills into Copilot CLI projects +- `validate-skills.sh`: new Copilot CLI compatibility checks (`${CLAUDE_PLUGIN_ROOT}` usage, `plugin.json` `skills` field, unsafe single-line `description:` colons) + +### Fixed + +- Skill `name:` frontmatter changed from `dev:` to `dev-` — Copilot CLI rejects `:` in skill names; verified this has no effect on Claude Code, whose `/dev:` invocation is driven by `commands/.md`, not this field +- Three files (`review-app/SKILL.md`, `commands/meta-install.md`, `commands/meta-create-skill.md`) had unquoted single-line `description:` values containing a colon followed by a space, which breaks YAML parsing under Copilot CLI's stricter parser +- Four `SKILL.md` files used `${CLAUDE_PLUGIN_ROOT}` (Claude Code-only template variable) for cross-file references — replaced with plain relative paths +- Stale "24 skills" / "26 skills" counts corrected to 27 across `marketplace.json`, `plugin.json`, `CLAUDE.md`, `README.md` + --- ## [2.0.0] — 2026-06-08 diff --git a/CLAUDE.md b/CLAUDE.md index d845cb6..458f7f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # Dev Best Practices -This repo contains best-practice rules for software projects (RAG systems, AI agents, data pipelines, full-stack web apps) and a **Claude Code Plugin** with 26 skills. +This repo contains best-practice rules for software projects (RAG systems, AI agents, data pipelines, full-stack web apps) and a **Claude Code Plugin** with 27 skills that also works as a **GitHub Copilot CLI plugin** (see "Copilot CLI Support" below). ## Repo Structure @@ -10,9 +10,9 @@ This repo contains best-practice rules for software projects (RAG systems, AI ag plugins/dev/ .claude-plugin/ - plugin.json # Plugin metadata (name: "dev", version: "3.0.0") - commands/ # Slash command definitions (one file per skill) - skills/ # Skill workflow definitions (auto-triggered) + plugin.json # Plugin metadata (name: "dev", version: "3.0.0") — also read by Copilot CLI (fallback lookup path) + commands/ # Slash command definitions (one file per skill) — Claude Code only, Copilot CLI has no equivalent + skills/ # Skill workflow definitions (auto-triggered) — shared by Claude Code and Copilot CLI rules/ # Mirror of claude/*.md (used by skills as reference) claude/ # Condensed rules for Claude Code @@ -33,7 +33,7 @@ scripts/ validate-skills.sh # Plugin structure validator (CI + pre-commit) ``` -## Plugin Skills (24) +## Plugin Skills (27) ```text DESIGN: design-app, design-secure, design-api, design-data, design-migration, @@ -49,12 +49,40 @@ Navigation menu: `/dev:meta-help` ## Usage in Projects -**Install plugin:** `claude plugin install dev@gerald-dev-best-practices` +**Install plugin (Claude Code):** `claude plugin install dev@gerald-dev-best-practices` + +**Install plugin (GitHub Copilot CLI):** `copilot plugin marketplace add gerfru/dev-best-practices` then `copilot plugin install dev@gerald-dev-best-practices` — see "Copilot CLI Support" below. **Rules only (without plugin):** Copy `claude/essential-rules.md` into project CLAUDE.md, or use `/dev:meta-install`. **More detail:** Selectively add sections from `claude/app-rules.md`, `claude/github-rules.md`, `claude/architecture-rules.md`. +## Copilot CLI Support + +This plugin is dual-compatible with Claude Code and GitHub Copilot CLI, since both tools +converged on a near-identical plugin architecture: + +- **Manifests are reused as-is.** `plugins/dev/.claude-plugin/plugin.json` sits at one of + Copilot CLI's fallback lookup paths and has no `skills` field — the exact condition both + tools need (Claude Code rejects a `skills` field; Copilot CLI auto-discovers `skills/` + only when it's absent). `.claude-plugin/marketplace.json` is also a valid Copilot CLI + lookup path. No second manifest or generated duplicate tree exists in this repo. +- **`SKILL.md` files use plain relative paths** (`../../rules/...`, `../other-skill/SKILL.md`) + for all cross-file references, never `${CLAUDE_PLUGIN_ROOT}` — that template variable is + Claude Code-only and Copilot CLI does not expand it. `${CLAUDE_PLUGIN_ROOT}` remains fine + inside `plugins/dev/commands/*.md`, which is Claude Code-only (Copilot CLI has no + slash-command-router concept — skills are natively slash-invocable there via discovery). +- **`meta-install` supports `--target claude|copilot-cli`** — for Copilot CLI it writes into + the same `CLAUDE.md` by default (Copilot CLI reads it directly as an instructions file), + or `.github/copilot-instructions.md` with `--copilot-native`. A `--standalone-skills` mode + copies the skill library into a project's `.github/skills/`, `.claude/skills/`, or + `.agents/skills/` for Copilot CLI users not using the plugin/marketplace mechanism. +- **Skill `name:` fields use `dev-` (hyphen, not colon).** Verified live: Copilot CLI + rejects `:` in skill names ("must contain only ASCII letters, numbers, hyphens, + underscores"); Claude Code's own `/dev:` slash-invocation is unaffected since it's + driven by `commands/.md` (plugin name + command filename), never by this + frontmatter field. + ## Maintenance - Update `reference/` when best practices change diff --git a/README.md b/README.md index 720208b..c4dfa78 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,14 @@ Opinionated best-practice rules for software projects — RAG systems, AI agents, data pipelines, full-stack web apps. Three detail levels: compact essential rules for `CLAUDE.md`, thematic rule files, and detailed reference docs. -Also a **Claude Code plugin**: install once, get 24 skills in every project. +Also a **Claude Code plugin**: install once, get 27 skills in every project. Also works as a **GitHub Copilot CLI plugin** — same repo, same skills. --- ## Quick Start +### Claude Code + ```bash # Add marketplace (once per machine) claude plugin marketplace add gerfru/dev-best-practices @@ -23,6 +25,24 @@ claude plugin install dev@gerald-dev-best-practices **Windows (VS Code):** Claude icon → `/plugin` → Marketplaces → add `gerfru/dev-best-practices` → Plugins → Install `dev`. +### GitHub Copilot CLI + +```bash +# Add marketplace (once per machine) +copilot plugin marketplace add gerfru/dev-best-practices + +# Install plugin +copilot plugin install dev@gerald-dev-best-practices +``` + +Skills are then invocable directly, e.g. `/dev:design-api`, or auto-triggered from a +natural-language prompt matching a skill's description — same as Claude Code. + +Not using Copilot's plugin/marketplace mechanism? Run `/dev:meta-install --target +copilot-cli --standalone-skills` from a Claude Code session against your target project to +copy the skill library into `.github/skills/`, `.claude/skills/`, or `.agents/skills/`, +where Copilot CLI auto-discovers it. + --- ## Skills @@ -69,7 +89,7 @@ Or just describe what you need in natural language — Claude picks the right sk | Skill | What it does | |---|---| -| `/dev:meta-help` | Navigation menu — shows all 24 skills, launches chosen one | +| `/dev:meta-help` | Navigation menu — shows all 27 skills, launches chosen one | | `/dev:meta-install` | Insert `essential-rules.md` into project `CLAUDE.md` (detects install vs. update) | | `/dev:meta-drift` | Compare installed rules block against current rule files | | `/dev:meta-sync` | Repo-internal: check if `claude/*.md` still reflects `reference/*.md` | @@ -85,9 +105,9 @@ Or just describe what you need in natural language — Claude picks the right sk plugins/dev/ .claude-plugin/ - plugin.json Plugin metadata (name: "dev", version: "2.0.0") - commands/ Slash-command definitions (one file per skill) - skills/ Skill workflow definitions (auto-triggered) + plugin.json Plugin metadata (name: "dev", version: "3.0.0") — also read by Copilot CLI + commands/ Slash-command definitions (one file per skill) — Claude Code only + skills/ Skill workflow definitions (auto-triggered) — shared with Copilot CLI rules/ Mirror of claude/*.md (used by skills as reference) claude/ Condensed rules for Claude Code diff --git a/plugins/dev/.claude-plugin/plugin.json b/plugins/dev/.claude-plugin/plugin.json index e17fb79..354a557 100644 --- a/plugins/dev/.claude-plugin/plugin.json +++ b/plugins/dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dev", "version": "3.0.0", - "description": "26 Skills für Design (inkl. LLM-Engineering/RAG/Agents, Observability/SRE, CI/CD, IaC/GitOps, UX/Human-AI Interaction, Repo-Publication), Security-Review (ISEC/Stanford/MIT, OWASP LLM Top 10), App-Audit (OWASP ASVS 5.0, DORA), Architektur-Review, Debug, Test, Styling, Accessibility (WCAG 2.2), Performance Engineering (MIT 6.172, USE Method) und Skill-Erstellung.", + "description": "27 Skills für Design (inkl. LLM-Engineering/RAG/Agents, Observability/SRE, CI/CD, IaC/GitOps, UX/Human-AI Interaction, Repo-Publication), Security-Review (ISEC/Stanford/MIT, OWASP LLM Top 10), App-Audit (OWASP ASVS 5.0, DORA), Architektur-Review, Debug, Test, Styling, Accessibility (WCAG 2.2), Performance Engineering (MIT 6.172, USE Method) und Skill-Erstellung. Funktioniert mit Claude Code und GitHub Copilot CLI.", "author": { "name": "Gerald" } } diff --git a/plugins/dev/commands/meta-create-skill.md b/plugins/dev/commands/meta-create-skill.md index c3ea3d6..f797e71 100644 --- a/plugins/dev/commands/meta-create-skill.md +++ b/plugins/dev/commands/meta-create-skill.md @@ -1,5 +1,11 @@ --- -description: Creates a new skill for this plugin following the established methodology: topic → academic research (university curricula + canonical books) → SKILL.md + references/. Use this skill when you want to create a new /dev skill. Trigger: "create a new skill", "build a new skill", "create skill for X", "add a skill", "add skill", "new skill for X". Covers: topic clarification, academic research, structure decision, writing all files, housekeeping (commands/, meta-help, plugin.json). +description: > + Creates a new skill for this plugin following the established methodology — topic → + academic research (university curricula + canonical books) → SKILL.md + references/. + Use this skill when you want to create a new /dev skill. Trigger phrases: "create a new + skill", "build a new skill", "create skill for X", "add a skill", "add skill", + "new skill for X". Covers topic clarification, academic research, structure decision, + writing all files, housekeeping (commands/, meta-help, plugin.json). argument-hint: "[optional: skill topic, e.g. 'LLM Engineering' or 'Performance Monitoring']" --- diff --git a/plugins/dev/commands/meta-install.md b/plugins/dev/commands/meta-install.md index e6bd65f..272f7fe 100644 --- a/plugins/dev/commands/meta-install.md +++ b/plugins/dev/commands/meta-install.md @@ -1,5 +1,8 @@ --- -description: Installs or updates dev best practices rules in CLAUDE.md. Automatically detects whether initial installation or update is needed. Flags: --essential (default), --full, --update, --section . +description: > + Installs or updates dev best practices rules in CLAUDE.md. Automatically detects + whether initial installation or update is needed. Flags — --essential (default), + --full, --update, --section . argument-hint: "[--essential | --full | --update | --section ]" --- diff --git a/plugins/dev/skills/design-api/SKILL.md b/plugins/dev/skills/design-api/SKILL.md index e9a6213..aa9eb49 100644 --- a/plugins/dev/skills/design-api/SKILL.md +++ b/plugins/dev/skills/design-api/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-api +name: dev-design-api description: > API contract design skill grounded in CMU 17-625 (API Design, Swarnalatha Ashok / Bradley Schmerl) and Google API Design Guide. Use this skill whenever the user diff --git a/plugins/dev/skills/design-app/SKILL.md b/plugins/dev/skills/design-app/SKILL.md index c8ee31e..ece0d9d 100644 --- a/plugins/dev/skills/design-app/SKILL.md +++ b/plugins/dev/skills/design-app/SKILL.md @@ -1,12 +1,12 @@ --- -name: dev:design-app +name: dev-design-app description: From an app idea to well-founded architecture and stack decisions based on the Dev-Best-Practices rules. Use this skill whenever the user describes a new app idea and wants help choosing architecture, stack, structure, or a scaffolding plan; triggers on "new app", "app idea", "how do I structure", "which stack", "architecture for ...". --- # App Design (rule-based) Turns an app idea into justified decisions. Standard: the rule files -under `${CLAUDE_PLUGIN_ROOT}/rules/` (especially architecture-rules.md, app-rules.md, +under `../../rules/` (especially architecture-rules.md, app-rules.md, github-rules.md). No generic advice — every decision references the rule. ## Step 0 - Clarify Idea & Scope diff --git a/plugins/dev/skills/design-cicd/SKILL.md b/plugins/dev/skills/design-cicd/SKILL.md index a47a18a..1735511 100644 --- a/plugins/dev/skills/design-cicd/SKILL.md +++ b/plugins/dev/skills/design-cicd/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-cicd +name: dev-design-cicd description: > CI/CD Pipeline Design grounded in "Accelerate" (Forsgren/Humble/Kim, IT Revolution 2018) and "Continuous Delivery" (Humble/Farley, Addison-Wesley 2010). Covers pipeline architecture, diff --git a/plugins/dev/skills/design-data/SKILL.md b/plugins/dev/skills/design-data/SKILL.md index 7da7347..fb032f7 100644 --- a/plugins/dev/skills/design-data/SKILL.md +++ b/plugins/dev/skills/design-data/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-data +name: dev-design-data description: > Data model design skill grounded in CMU 15-445 (Database Systems, Prof. Andy Pavlo) and Stanford CS245. Use this skill whenever the user needs to design or review a diff --git a/plugins/dev/skills/design-iac/SKILL.md b/plugins/dev/skills/design-iac/SKILL.md index ccddb85..9b5dbff 100644 --- a/plugins/dev/skills/design-iac/SKILL.md +++ b/plugins/dev/skills/design-iac/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-iac +name: dev-design-iac description: > Infrastructure as Code Design grounded in "Infrastructure as Code" (Kief Morris, O'Reilly 2021) and NTNU IIKG3005 (the only dedicated academic IaC course worldwide). diff --git a/plugins/dev/skills/design-llm/SKILL.md b/plugins/dev/skills/design-llm/SKILL.md index 3f7fc16..65a4503 100644 --- a/plugins/dev/skills/design-llm/SKILL.md +++ b/plugins/dev/skills/design-llm/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-llm +name: dev-design-llm description: > LLM system design grounded in Stanford CS224N (Yang/Choi), CMU 11-667 (Savelka/Kim) and Chip Huyen "Designing ML Systems". Use this skill whenever diff --git a/plugins/dev/skills/design-migration/SKILL.md b/plugins/dev/skills/design-migration/SKILL.md index 4e82ae3..9a0e28e 100644 --- a/plugins/dev/skills/design-migration/SKILL.md +++ b/plugins/dev/skills/design-migration/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-migration +name: dev-design-migration description: > Migration planning skill grounded in MIT 6.5840 (Distributed Systems, Morris/ Kaashoek/Zeldovich) and Martin Fowler's migration patterns. Use this skill diff --git a/plugins/dev/skills/design-observability/SKILL.md b/plugins/dev/skills/design-observability/SKILL.md index 8ff9cb6..eb41714 100644 --- a/plugins/dev/skills/design-observability/SKILL.md +++ b/plugins/dev/skills/design-observability/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-observability +name: dev-design-observability description: > Observability architecture grounded in the Google SRE Books (Beyer et al.) and Observability Engineering (Majors/Fong-Jones, O'Reilly 2022). Covers diff --git a/plugins/dev/skills/design-public/SKILL.md b/plugins/dev/skills/design-public/SKILL.md index f42550c..9d0d0f8 100644 --- a/plugins/dev/skills/design-public/SKILL.md +++ b/plugins/dev/skills/design-public/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-public +name: dev-design-public description: > Publication-readiness design skill grounded in OpenSSF Best Practices, GitHub Security Hardening docs, CISA Security-by-Design, OWASP DevSecOps diff --git a/plugins/dev/skills/design-secure/SKILL.md b/plugins/dev/skills/design-secure/SKILL.md index e1006ab..3262a21 100644 --- a/plugins/dev/skills/design-secure/SKILL.md +++ b/plugins/dev/skills/design-secure/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-secure +name: dev-design-secure description: > Security-first application design skill grounded in TU Graz ISEC Major curriculum and top-university references (Stanford CS255/CS355, MIT 6.566/6.5610). diff --git a/plugins/dev/skills/design-ux/SKILL.md b/plugins/dev/skills/design-ux/SKILL.md index e35073e..0990ae4 100644 --- a/plugins/dev/skills/design-ux/SKILL.md +++ b/plugins/dev/skills/design-ux/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:design-ux +name: dev-design-ux description: > Human-Centered UX Design skill grounded in the leading academic HCI curricula (CMU HCII, Stanford CS 247A/347, ETH, TU Wien, TU Graz) and the four canonical diff --git a/plugins/dev/skills/meta-create-skill/SKILL.md b/plugins/dev/skills/meta-create-skill/SKILL.md index d339509..aa9017a 100644 --- a/plugins/dev/skills/meta-create-skill/SKILL.md +++ b/plugins/dev/skills/meta-create-skill/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:meta-create-skill +name: dev-meta-create-skill description: > Creates a new skill for this plugin following the established methodology: topic → academic research (university curricula + canonical books) → SKILL.md + @@ -99,6 +99,11 @@ What belongs IN SKILL.md: - Standard finding format (for review-* skills) - Output format (which file, which structure) - References to references/ files +- Cross-file references as **plain relative paths** (e.g. `../../rules/essential-rules.md`, + `../other-skill/SKILL.md`) — **never `${CLAUDE_PLUGIN_ROOT}`**. That variable is Claude + Code-only template syntax; it breaks silently under GitHub Copilot CLI, which also reads + this plugin's `skills/` directory but does not expand it. `${CLAUDE_PLUGIN_ROOT}` is + permitted only inside `commands/.md` (a Claude-Code-only file Copilot never parses). What does NOT belong in SKILL.md (→ references/): - Lookup tables (Concept → course link) @@ -173,7 +178,7 @@ Required elements: ```markdown --- -name: +name: dev- description: > . Grounded in . Trigger: "", "", ... @@ -209,6 +214,18 @@ description: > - `references/.md` — ``` +**Note:** `name:` uses `dev-` (hyphen, not colon). Verified against a live +Copilot CLI install: `:` is rejected ("Skill name must start with an ASCII letter or +number and contain only ASCII letters, numbers, hyphens, underscores"), so `dev:` +produced a load warning on every skill under Copilot CLI (non-fatal there — it fell back +to the folder name — but still worth avoiding). `dev-` is ASCII-clean for Copilot. +Also verified live against Claude Code after this rename: `/dev:` +slash-invocation is driven entirely by `commands/.md` (plugin name from +`plugin.json` + the command file's own name) — it never reads this SKILL.md frontmatter +field at all, so the rename has zero effect on Claude Code's routing. Any cross-file +reference in the body must be a plain relative path regardless — see the rule under +Step 2a. + ### 3c — commands/.md ```markdown diff --git a/plugins/dev/skills/meta-drift/SKILL.md b/plugins/dev/skills/meta-drift/SKILL.md index 15caddb..123e325 100644 --- a/plugins/dev/skills/meta-drift/SKILL.md +++ b/plugins/dev/skills/meta-drift/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:meta-drift +name: dev-meta-drift description: Compares the dev-best-practices block in a project CLAUDE.md with the current state of the rule files and shows what is missing, outdated, or newly added. Use this skill whenever the user wants to update their project rules, check if rules are still current, or sync a CLAUDE.md with the latest best practices; triggers for "update rules", "are my rules still current", "drift", "sync CLAUDE.md", "update rules". --- @@ -10,7 +10,7 @@ Shows the delta — without automatically overwriting. ## Step 0 — Load Sources -1. **Current state (TARGET):** Rule files from `${CLAUDE_PLUGIN_ROOT}/rules/` +1. **Current state (TARGET):** Rule files from `../../rules/` - `essential-rules.md` — always - `app-rules.md`, `github-rules.md`, `architecture-rules.md` — only if present in the project block diff --git a/plugins/dev/skills/meta-help/SKILL.md b/plugins/dev/skills/meta-help/SKILL.md index 941b9a6..d7ddd12 100644 --- a/plugins/dev/skills/meta-help/SKILL.md +++ b/plugins/dev/skills/meta-help/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:meta-help +name: dev-meta-help description: > Navigation menu for all Dev Best Practices skills. Shows all available skills grouped and starts the chosen one directly. Trigger for "which skill should I use", @@ -61,9 +61,9 @@ Which skill should start? **With a description:** Choose the best matching skill, mention it briefly ("→ starting review-secure …"), then start directly. **With arguments:** Pass to the started skill. -Load and follow exactly: `${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md` +Load and follow exactly: `..//SKILL.md` ## Rules - Show menu immediately, no intro - After the choice: start directly, do not explain or ask again -- Never load all 26 skills at once — always only the chosen one +- Never load all 27 skills at once — always only the chosen one diff --git a/plugins/dev/skills/meta-install/SKILL.md b/plugins/dev/skills/meta-install/SKILL.md index 6424ba0..58e670d 100644 --- a/plugins/dev/skills/meta-install/SKILL.md +++ b/plugins/dev/skills/meta-install/SKILL.md @@ -1,28 +1,44 @@ --- -name: dev:meta-install -description: Adds the dev best practices rules as a structured block to the CLAUDE.md of a target project — or updates an existing block. Use this skill whenever the user wants to add or update best-practice rules in a project CLAUDE.md; triggers for "set up rules", "install rules", "update rules", "CLAUDE.md setup", "update best practices", "update rules". +name: dev-meta-install +description: Adds the dev best practices rules as a structured block to the CLAUDE.md (or, for Copilot CLI, optionally .github/copilot-instructions.md) of a target project — or updates an existing block. Can also copy the skill library itself into a project for standalone GitHub Copilot CLI discovery. Use this skill whenever the user wants to add or update best-practice rules in a project, or wants these skills available under GitHub Copilot CLI; triggers for "set up rules", "install rules", "update rules", "CLAUDE.md setup", "update best practices", "update rules", "install for copilot", "copilot cli setup", "standalone skills". --- # Install Rules -Inserts `essential-rules.md` (or selected sections) as a dedicated block into the -`CLAUDE.md` of a target project — or updates an existing block in-place. +Inserts `essential-rules.md` (or selected sections) as a dedicated block into a +target project's instructions file — or updates an existing block in-place. Existing project context and project exceptions are never overwritten. +Can also copy the skill library into a project for tools without a plugin/marketplace +mechanism (Copilot CLI standalone mode). -## Step 0 — Detect Mode (Install vs. Update) +## Step 0 — Determine Target & Mode -1. **Locate target `CLAUDE.md`** (current directory `./CLAUDE.md`) +1. **Determine target** (flag `--target claude|copilot-cli`, default `claude`): + - `--target claude` (default): write into `./CLAUDE.md` — unchanged, existing behavior. + - `--target copilot-cli`: write into `./CLAUDE.md` as well by default — GitHub Copilot + CLI reads `CLAUDE.md` directly as a first-class instructions file, so no separate + file is needed. If the user passes `--copilot-native`, write into + `./.github/copilot-instructions.md` instead (same block format), for projects that + want a Copilot-idiomatic file and don't use Claude Code at all. + - **If both `./CLAUDE.md` (with an existing `DEV-BEST-PRACTICES` block) and + `./.github/copilot-instructions.md` would end up existing at once:** warn the user + explicitly in the Step 3 preview — GitHub Copilot CLI defines no precedence order + between multiple instruction files and only warns to "avoid conflicting + instructions," so duplicated blocks across two files should be a deliberate choice, + not an accident. -2. **Determine mode:** +2. **Locate target file** (per the resolved target/flag above). + +3. **Determine mode:** | Situation | Mode | |---|---| - | No `CLAUDE.md` present | **Create new** | - | `CLAUDE.md` without `DEV-BEST-PRACTICES:START` marker | **Initial install** | - | `CLAUDE.md` with `DEV-BEST-PRACTICES:START` marker | **Update** | + | Target file not present | **Create new** | + | Target file without `DEV-BEST-PRACTICES:START` marker | **Initial install** | + | Target file with `DEV-BEST-PRACTICES:START` marker | **Update** | | `--force` flag | **Update** even without marker (regenerate block) | -3. **Determine scope** (default: `--essential`): +4. **Determine scope** (default: `--essential`): - `--essential` → only `essential-rules.md` (~80 lines, recommended) - `--full` → all four rule files (essential + app + github + architecture) - `--section ` → individual section, e.g. `--section security` @@ -30,9 +46,13 @@ Existing project context and project exceptions are never overwritten. If no specification and update mode: retain the scope documented in the marker. +5. **Standalone skills mode** (`--target copilot-cli --standalone-skills`): skip + rules-block installation entirely and go to Step 4 instead — this mode copies the + skill library itself rather than the rules text. + ## Step 1 — Prepare Rules -1. Read the chosen rule files from `${CLAUDE_PLUGIN_ROOT}/rules/` +1. Read the chosen rule files from `../../rules/` 2. For `--section`: extract the relevant section 3. Check if rules fit the detected stack: - Python project without TypeScript → mark TypeScript-specific rules as `[optional]` @@ -44,7 +64,7 @@ Existing project context and project exceptions are never overwritten. **Block format:** ```markdown - + ## Dev Best Practices @@ -71,7 +91,7 @@ Existing project context and project exceptions are never overwritten. 4. **Update version marker:** ```text - + ``` **What is never touched during an update:** @@ -85,13 +105,19 @@ Existing project context and project exceptions are never overwritten. ```text Mode: [Initial install / Update] -File: ./CLAUDE.md +Target: claude | copilot-cli +File: ./CLAUDE.md (or ./.github/copilot-instructions.md with --copilot-native) Scope: essential-rules.md (78 lines) [Update] Old block: Version from , X lines [Update] New block: Version from today, Y lines [Update] Saved project exceptions: Z items +[If both CLAUDE.md and .github/copilot-instructions.md would exist with a block] +⚠ Both CLAUDE.md and .github/copilot-instructions.md contain a Dev Best Practices + block. Copilot CLI defines no precedence between them — keep both in sync manually + or pick one. + Changes outside the block: none Proceed? (yes/no) @@ -102,10 +128,35 @@ After writing: - On update: `Project exceptions preserved: Z items` - Next step: `check-drift` runs automatically for verification +## Step 4 — Standalone Skills Mode (`--target copilot-cli --standalone-skills`) + +For projects that don't use Copilot CLI's plugin/marketplace mechanism at all and want +the skill library available via Copilot's standalone skill discovery. + +1. **Ask which discovery location** the project should use (Copilot CLI checks all + three, project-scoped): `.github/skills/`, `.claude/skills/`, or `.agents/skills/`. + Call this `` below (e.g. `.github/skills/`). +2. **Copy each `..//` skill directory** (all 27 — `SKILL.md` plus any + `references/`) directly into `//` (e.g. `.github/skills/design-api/`). + The relative-path convention from Step 1's fix means this is a plain recursive copy, + no rewriting needed. +3. **Also copy `../../rules/`** (all four rule files) into the parent of ``, + under `rules/` (e.g. `.github/skills/` → copy to `.github/rules/`) — `meta-install` + and `meta-drift` resolve `../../rules/` relative to their own `SKILL.md` inside + `//`, so without this the two rules-related skills would be copied + but broken. +4. **Report** exactly which skill directories and rule files were copied and where. +5. **Note the limitation explicitly:** standalone-copied skills have no autoUpdate — + future rule/skill changes require re-running this step manually. This is unlike the + marketplace install path, which stays current automatically. + ## Rules - Only write after confirmation. - Never touch content outside the markers. - Always preserve project exceptions — they are deliberate deviations, not errors. -- If `CLAUDE.md` does not exist: create file with project placeholder + rules block. -- After every update call the `check-drift` skill to verify the new block - was inserted correctly. +- If the target file does not exist: create it with project placeholder + rules block. +- After every rules-block update call the `check-drift` skill to verify the new block + was inserted correctly. (Standalone skills mode has no drift-check equivalent — see + its noted limitation above.) +- Default target is always `claude` unless `--target copilot-cli` is explicitly given — + never change behavior for existing callers. diff --git a/plugins/dev/skills/meta-sync/SKILL.md b/plugins/dev/skills/meta-sync/SKILL.md index e6e8e84..d8e2bbd 100644 --- a/plugins/dev/skills/meta-sync/SKILL.md +++ b/plugins/dev/skills/meta-sync/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:meta-sync +name: dev-meta-sync description: Checks whether the compact claude/*.md rule files still reflect the essence of the detailed reference/*.md — finds sections that are new/changed in reference/ but not yet transferred to claude/. Use this skill for maintaining this dev-best-practices repo itself; triggers for "synchronize rules", "update reference", "claude/ sync", "are the rules still current", repo maintenance. ONLY for the dev-best-practices repo itself — not for other projects. --- diff --git a/plugins/dev/skills/review-app/SKILL.md b/plugins/dev/skills/review-app/SKILL.md index cec6403..1f47bfc 100644 --- a/plugins/dev/skills/review-app/SKILL.md +++ b/plugins/dev/skills/review-app/SKILL.md @@ -1,6 +1,16 @@ --- -name: dev:review-app -description: Complete end-to-end evaluation of an app/codebase — measures the codebase against the dev-best-practices rules of this repo (essential/app/github/architecture). Axes: Architecture (12-Factor), Security (OWASP ASVS 5.0/Top 10), CI-CD-Delivery (DORA), Code Quality, Tests, Observability. Use this skill whenever the user wants to audit, evaluate, review or assess an entire app or codebase, check production/release readiness, find technical debt, or do a security/architecture review. Trigger also for "evaluate/audit/review my app", "is my app release-ready", "security review", "architecture check" — even if only a single axis is mentioned. If you want to review architecture OR security: use this skill — it covers both. review-arch and review-secure are deep-dives for the respective focus; review-app is the complete overview. +name: dev-review-app +description: > + Complete end-to-end evaluation of an app/codebase — measures the codebase against + the dev-best-practices rules of this repo (essential/app/github/architecture). + Axes: Architecture (12-Factor), Security (OWASP ASVS 5.0/Top 10), CI-CD-Delivery (DORA), + Code Quality, Tests, Observability. Use this skill whenever the user wants to audit, + evaluate, review or assess an entire app or codebase, check production/release readiness, + find technical debt, or do a security/architecture review. Trigger also for + "evaluate/audit/review my app", "is my app release-ready", "security review", + "architecture check" — even if only a single axis is mentioned. If you want to review + architecture OR security, use this skill — it covers both. review-arch and review-secure + are deep-dives for the respective focus; review-app is the complete overview. --- # App Evaluation (repo-integrated) diff --git a/plugins/dev/skills/review-arch/SKILL.md b/plugins/dev/skills/review-arch/SKILL.md index 33cbfef..bfaace4 100644 --- a/plugins/dev/skills/review-arch/SKILL.md +++ b/plugins/dev/skills/review-arch/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:review-arch +name: dev-review-arch description: > Architecture review skill grounded in CMU 17-633 (Architectures for Software Systems, Prof. David Garlan) and Martin Fowler's architectural patterns. diff --git a/plugins/dev/skills/review-llm/SKILL.md b/plugins/dev/skills/review-llm/SKILL.md index 8067037..d414136 100644 --- a/plugins/dev/skills/review-llm/SKILL.md +++ b/plugins/dev/skills/review-llm/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:review-llm +name: dev-review-llm description: > LLM system review grounded in CMU 11-667 (Harms + Attacking LLMs), Berkeley CS294-196 (Safety/Guardrails), and OWASP LLM Top 10. Use this skill diff --git a/plugins/dev/skills/review-public/SKILL.md b/plugins/dev/skills/review-public/SKILL.md index e7a9c9b..5cfaf71 100644 --- a/plugins/dev/skills/review-public/SKILL.md +++ b/plugins/dev/skills/review-public/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:review-public +name: dev-review-public description: > Pre-publication repository scan grounded in OpenSSF Best Practices, GitHub Security Hardening docs, CISA Security-by-Design (2023), OWASP DevSecOps diff --git a/plugins/dev/skills/review-secure/SKILL.md b/plugins/dev/skills/review-secure/SKILL.md index 9490d49..c28c519 100644 --- a/plugins/dev/skills/review-secure/SKILL.md +++ b/plugins/dev/skills/review-secure/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:review-secure +name: dev-review-secure description: > Security-focused code review skill grounded in TU Graz ISEC Major curriculum and top-university references (Stanford CS255/CS355, MIT 6.566/6.5610, CMU 15-414). diff --git a/plugins/dev/skills/review-ux/SKILL.md b/plugins/dev/skills/review-ux/SKILL.md index 504cded..72f3ecb 100644 --- a/plugins/dev/skills/review-ux/SKILL.md +++ b/plugins/dev/skills/review-ux/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:review-ux +name: dev-review-ux description: > Systematic UX audit of an existing product, feature, or design against the four canonical Human-AI Interaction frameworks: Microsoft HAX 18 Guidelines diff --git a/plugins/dev/skills/tool-a11y/SKILL.md b/plugins/dev/skills/tool-a11y/SKILL.md index 00ec3e6..3c7eba3 100644 --- a/plugins/dev/skills/tool-a11y/SKILL.md +++ b/plugins/dev/skills/tool-a11y/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:tool-a11y +name: dev-tool-a11y description: > Accessibility audit workflow grounded in WCAG 2.2 (W3C), CMU HCII 05-332 (Prof. Carrington) and W3C WAI Digital Accessibility Foundations. Covers diff --git a/plugins/dev/skills/tool-debug/SKILL.md b/plugins/dev/skills/tool-debug/SKILL.md index 61ac729..3c362ea 100644 --- a/plugins/dev/skills/tool-debug/SKILL.md +++ b/plugins/dev/skills/tool-debug/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:tool-debug +name: dev-tool-debug description: Stack-aware debugging assistant. Analyzes an error or unexpected behavior, automatically detects the stack/framework, and delivers a structured root-cause plan with concrete fix suggestions. Use this skill whenever the user reports a bug, error message, unexpected behavior, or asks "why does X not work"; triggers for "error", "bug", "not working", "debug", "why does X happen", stack traces, or unexpected output. --- diff --git a/plugins/dev/skills/tool-perf/SKILL.md b/plugins/dev/skills/tool-perf/SKILL.md index fc5edf3..8825741 100644 --- a/plugins/dev/skills/tool-perf/SKILL.md +++ b/plugins/dev/skills/tool-perf/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:tool-perf +name: dev-tool-perf description: > Performance engineering workflow grounded in MIT 6.172 (Leiserson/Shun, fully available on MIT OCW) and "Systems Performance" (Brendan Gregg, diff --git a/plugins/dev/skills/tool-style/SKILL.md b/plugins/dev/skills/tool-style/SKILL.md index 3129092..439beeb 100644 --- a/plugins/dev/skills/tool-style/SKILL.md +++ b/plugins/dev/skills/tool-style/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:tool-style +name: dev-tool-style description: Stack-aware frontend styling assistant. Automatically detects the CSS framework, design system, and component library, then delivers consistent, maintainable styling decisions and fixes. Includes visual design fundamentals (color, typography, spacing, loading states) for developers without a design background. Use this skill whenever the user has a frontend styling question, wants to fix visual inconsistencies, improve CSS architecture, work with a component library, or needs practical design guidance (colors, typography, dark mode, skeleton screens); triggers for "styling", "CSS", "design system", "component looks wrong", "theme", "responsive", "Tailwind", "SCSS", "colors", "color system", "skeleton", "loading state", UI questions. --- diff --git a/plugins/dev/skills/tool-test/SKILL.md b/plugins/dev/skills/tool-test/SKILL.md index 0bd5ce7..bcd7423 100644 --- a/plugins/dev/skills/tool-test/SKILL.md +++ b/plugins/dev/skills/tool-test/SKILL.md @@ -1,5 +1,5 @@ --- -name: dev:tool-test +name: dev-tool-test description: Stack-aware test assistant. Automatically detects language, framework, and existing test setup, then designs or generates appropriate tests (unit, integration, E2E) according to the test pyramid. Use this skill whenever the user wants to write, improve, or review tests; triggers for "write tests", "test strategy", "increase coverage", "how do I test X", "missing tests", "flaky tests". --- diff --git a/scripts/validate-skills.sh b/scripts/validate-skills.sh index 7c5e097..0e5a90c 100644 --- a/scripts/validate-skills.sh +++ b/scripts/validate-skills.sh @@ -72,6 +72,61 @@ else done fi +# --- Copilot CLI compatibility --- +echo "=== copilot-cli compatibility ===" +if [[ -f "$PLUGIN_JSON" ]] && json_has_field "skills" "$PLUGIN_JSON"; then + fail "$PLUGIN_JSON: has a 'skills' field — Claude Code rejects this; remove it (Copilot CLI auto-discovers skills/ when absent)" +else + pass "plugin.json has no 'skills' field (required for Copilot CLI auto-discovery)" +fi + +if [[ -d "$PLUGIN_DIR/skills" ]]; then + for skill_dir in "$PLUGIN_DIR/skills"/*/; do + [[ -d "$skill_dir" ]] || continue + skill_name=$(basename "$skill_dir") + skill_md="$skill_dir/SKILL.md" + [[ -f "$skill_md" ]] || continue + + # meta-create-skill documents the ${CLAUDE_PLUGIN_ROOT} anti-pattern by name — exempt it + if [[ "$skill_name" == "meta-create-skill" ]]; then + pass "[$skill_name] exempt (documents \${CLAUDE_PLUGIN_ROOT} as prohibited pattern by name)" + elif grep -q 'CLAUDE_PLUGIN_ROOT' "$skill_md"; then + fail "[$skill_name] SKILL.md uses \${CLAUDE_PLUGIN_ROOT} — breaks Copilot CLI, use a relative path instead" + else + pass "[$skill_name] SKILL.md has no \${CLAUDE_PLUGIN_ROOT} usage" + fi + done +fi + +# A single-line (non-block-scalar) `description:` containing ": " breaks YAML parsing +# under Copilot CLI's stricter frontmatter parser ("mapping values are not allowed in +# this context") even though Claude Code tolerates it. Use `description: >` (folded +# block scalar) instead whenever the text needs an embedded colon. +check_description_colon() { + local f="$1" + local line + line=$(grep -m1 '^description:' "$f" || true) + [[ -z "$line" || "$line" == "description: >" || "$line" == "description: |" ]] && return 0 + local rest="${line#description: }" + if echo "$rest" | grep -qE ': '; then + fail "[$(basename "$f")] single-line description contains ': ' — breaks Copilot CLI YAML parsing, switch to 'description: >' block style" + return 1 + fi + return 0 +} + +echo "=== copilot-cli yaml safety (description colon check) ===" +for skill_md in "$PLUGIN_DIR"/skills/*/SKILL.md; do + [[ -f "$skill_md" ]] || continue + check_description_colon "$skill_md" && pass "[$(basename "$(dirname "$skill_md")")] description has no unsafe ': '" +done +if [[ -d "$PLUGIN_DIR/commands" ]]; then + for cmd_file in "$PLUGIN_DIR/commands"/*.md; do + [[ -f "$cmd_file" ]] || continue + check_description_colon "$cmd_file" && pass "[$(basename "$cmd_file" .md)] description has no unsafe ': '" + done +fi + # --- Commands: frontmatter + referenced skill must exist --- echo "=== commands ===" if [[ -d "$PLUGIN_DIR/commands" ]]; then