Add style-aware AI skill installation

Author: Copilot

README.md

@@ -76,7 +76,7 @@ The fastest way to get started is to let your AI coding assistant build your fir
 plugboard ai init
 ```
 
-This copies a context file (`AGENTS.md`) and a `skills/` directory into your project so your AI tool has Plugboard-specific guidance for structuring models, keeping component arguments YAML-friendly, exporting configs, generating diagrams, running scenarios, and setting up tuning.
+This copies a context file (`AGENTS.md`) and installs Agent Skills into `.agents/skills/` by default (or `.github/skills/` / `.claude/skills/` with `--style`) so your AI tool has Plugboard-specific guidance for structuring models, keeping component arguments YAML-friendly, exporting configs, generating diagrams, running scenarios, and setting up tuning.
 
 Once initialised, simply open your AI tool of choice (GitHub Copilot, Cursor, Claude, etc.) and describe the model you want to build. For example:
 

docs/usage/ai.md

@@ -4,7 +4,7 @@ Plugboard ships with tooling to help AI coding agents understand how to build mo
 
 ## Initialising a project
 
-The `plugboard ai init` command creates an `AGENTS.md` file and a `skills/` directory in your project directory. Together they give AI coding agents the context they need to help you build, export, visualise, run, and tune Plugboard models.
+The `plugboard ai init` command creates an `AGENTS.md` file and installs Agent Skills in your project directory. Together they give AI coding agents the context they need to help you build, export, visualise, run, and tune Plugboard models.
 
 `AGENTS.md` is a convention used by AI coding tools (such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Codex](https://openai.com/index/codex/), and [Gemini CLI](https://github.com/google-gemini/gemini-cli)) to discover project-specific instructions automatically.
 
@@ -22,8 +22,14 @@ To create the file in a specific directory:
 plugboard ai init /path/to/project
 ```
 
+To choose where the skills are installed:
+
+```bash
+plugboard ai init --style github
+```
+
 !!! note
-    The command will not overwrite an existing `AGENTS.md` file or `skills/` directory. If either already exists in the target directory, the command exits with an error.
+    The command will not overwrite an existing `AGENTS.md` file or the selected skills directory. If either already exists in the target directory, the command exits with an error.
 
 ### What's installed?
 
@@ -37,7 +43,13 @@ The generated `AGENTS.md` covers:
 - **Event-driven models** — defining custom [`Event`][plugboard.events.Event] types, emitting events, and writing event handlers.
 - **Exporting models** — saving process definitions to YAML and running them via the CLI.
 
-The generated `skills/` directory includes reusable task guides for:
+The generated skills use the Agent Skills `SKILL.md` format with frontmatter, and are installed into one of these directories:
+
+- `.agents/skills/` for `--style agents` (default)
+- `.github/skills/` for `--style github`
+- `.claude/skills/` for `--style claude`
+
+The generated skills include reusable task guides for:
 
 - creating a YAML config from a model defined in Python
 - generating a process diagram with `plugboard process diagram`

plugboard/cli/ai/AGENTS.md

@@ -32,12 +32,18 @@ Use this sequence when helping a user plan, implement, and run a Plugboard model
 
 ## Skill files
 
-Additional task-specific instructions are available in `./skills/`. When a user asks for one of these tasks, read the matching `SKILLS.md` file and follow it:
+Additional task-specific instructions are available in a style-specific skills directory. Depending on the setup, look under one of:
 
-- `skills/create-yaml-config/SKILLS.md`
-- `skills/process-diagram/SKILLS.md`
-- `skills/run-process-scenario/SKILLS.md`
-- `skills/configure-tune/SKILLS.md`
+- `./.agents/skills/`
+- `./.github/skills/`
+- `./.claude/skills/`
+
+When a user asks for one of these tasks, read the matching `SKILL.md` file and follow it:
+
+- `create-yaml-config/SKILL.md`
+- `process-diagram/SKILL.md`
+- `run-process-scenario/SKILL.md`
+- `configure-tune/SKILL.md`
 
 ## Planning a model
 

plugboard/cli/ai/__init__.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 import shutil
+import typing as _t
 
 from rich import print
 from rich.console import Console
@@ -15,28 +16,45 @@
 
 _AGENTS_MD = Path(__file__).parent / "AGENTS.md"
 _SKILLS_DIR = Path(__file__).parent / "skills"
+_STYLE_SKILLS_DIRS: dict[str, Path] = {
+    "agents": Path(".agents/skills"),
+    "github": Path(".github/skills"),
+    "claude": Path(".claude/skills"),
+}
 
 
 @app.command()
 def init(
     directory: Path = typer.Argument(
         default=None,
         help=(
-            "Target directory for the AGENTS.md file and skills directory. "
+            "Target directory for the AGENTS.md file and style-specific skills directory. "
             "Defaults to the current working directory."
         ),
         exists=True,
         file_okay=False,
         dir_okay=True,
         resolve_path=True,
     ),
+    style: _t.Annotated[
+        _t.Literal["claude", "github", "agents"],
+        typer.Option(
+            "--style",
+            help=(
+                "Skill installation style. "
+                "Options: 'agents' for .agents/skills, "
+                "'github' for .github/skills, "
+                "'claude' for .claude/skills."
+            ),
+        ),
+    ] = "agents",
 ) -> None:
     """Initialise a project with Plugboard AI guidance files."""
     if directory is None:
         directory = Path.cwd()
 
     agents_target = directory / "AGENTS.md"
-    skills_target = directory / "skills"
+    skills_target = directory / _STYLE_SKILLS_DIRS[style]
     existing_paths = [path.name for path in (agents_target, skills_target) if path.exists()]
 
     if existing_paths:

…d/cli/ai/skills/configure-tune/SKILLS.md …rd/cli/ai/skills/configure-tune/SKILL.mdplugboard/cli/ai/skills/configure-tune/SKILLS.md renamed to plugboard/cli/ai/skills/configure-tune/SKILL.md plugboard/cli/ai/skills/configure-tune/SKILLS.md renamed to plugboard/cli/ai/skills/configure-tune/SKILL.md

@@ -1,4 +1,9 @@
-# Skill: Add a `tune` section to a Plugboard YAML config
+---
+name: configure-tune
+description: Add and shape a tune section in a Plugboard YAML configuration.
+---
+
+# Add a `tune` section to a Plugboard YAML config
 
 ## Use this skill when
 

…i/ai/skills/create-yaml-config/SKILLS.md …li/ai/skills/create-yaml-config/SKILL.mdplugboard/cli/ai/skills/create-yaml-config/SKILLS.md renamed to plugboard/cli/ai/skills/create-yaml-config/SKILL.md plugboard/cli/ai/skills/create-yaml-config/SKILLS.md renamed to plugboard/cli/ai/skills/create-yaml-config/SKILL.md

@@ -1,4 +1,9 @@
-# Skill: Create a YAML config from a Python-defined Plugboard model
+---
+name: create-yaml-config
+description: Create a YAML configuration from a Plugboard process defined in Python code.
+---
+
+# Create a YAML config from a Python-defined Plugboard model
 
 ## Use this skill when
 

…/cli/ai/skills/process-diagram/SKILLS.md …d/cli/ai/skills/process-diagram/SKILL.mdplugboard/cli/ai/skills/process-diagram/SKILLS.md renamed to plugboard/cli/ai/skills/process-diagram/SKILL.md plugboard/cli/ai/skills/process-diagram/SKILLS.md renamed to plugboard/cli/ai/skills/process-diagram/SKILL.md

@@ -1,4 +1,9 @@
-# Skill: Create a diagram from a Plugboard process
+---
+name: process-diagram
+description: Generate a Mermaid diagram from a Plugboard YAML process configuration.
+---
+
+# Create a diagram from a Plugboard process
 
 ## Use this skill when
 
@@ -11,7 +16,7 @@ Create a diagram from a Plugboard process using the CLI.
 
 ## Instructions
 
-1. Work from a YAML config whenever possible. If the process only exists in Python, first create a YAML config using the `skills/create-yaml-config/SKILLS.md` guidance.
+1. Work from a YAML config whenever possible. If the process only exists in Python, first use the `create-yaml-config` skill at `../create-yaml-config/SKILL.md`.
 2. Confirm which YAML config should be used. If the user wants the diagram saved to a file, plan to capture the CLI output.
 3. Run:
 

…ai/skills/run-process-scenario/SKILLS.md …/ai/skills/run-process-scenario/SKILL.mdplugboard/cli/ai/skills/run-process-scenario/SKILLS.md renamed to plugboard/cli/ai/skills/run-process-scenario/SKILL.md plugboard/cli/ai/skills/run-process-scenario/SKILLS.md renamed to plugboard/cli/ai/skills/run-process-scenario/SKILL.md

@@ -1,4 +1,9 @@
-# Skill: Run a Plugboard process for a specific scenario
+---
+name: run-process-scenario
+description: Update a Plugboard YAML config for a requested scenario and run it with the CLI.
+---
+
+# Run a Plugboard process for a specific scenario
 
 ## Use this skill when
 
@@ -11,7 +16,7 @@ Create or update a YAML config for the requested scenario, then run it with `plu
 
 ## Instructions
 
-1. Make sure a YAML config exists for the model. If the model only exists in Python, create the YAML first using the `skills/create-yaml-config/SKILLS.md` guidance.
+1. Make sure a YAML config exists for the model. If the model only exists in Python, create the YAML first by using the `create-yaml-config` skill at `../create-yaml-config/SKILL.md`.
 2. Ask for any missing scenario inputs before running anything.
 3. Update the YAML config with the exact parameter values the user requested.
 4. Preserve a clear component structure that matches the real-world model. Do not collapse multiple entities into one component just to make the config shorter.

tests/unit/test_cli.py

@@ -149,22 +149,33 @@ def test_cli_process_validate_invalid() -> None:
 
 
 def test_cli_ai_init(tmp_path: Path) -> None:
-    """Tests the ai init command creates AGENTS.md and skills."""
+    """Tests the ai init command creates AGENTS.md and agent-style skills."""
     result = runner.invoke(app, ["ai", "init", str(tmp_path)])
     assert result.exit_code == 0
     assert "Created" in result.stdout
     agents_md = tmp_path / "AGENTS.md"
-    skills_dir = tmp_path / "skills"
-    skill_files = sorted(skills_dir.glob("*/SKILLS.md"))
+    skills_dir = tmp_path / ".agents" / "skills"
+    skill_files = sorted(skills_dir.glob("*/SKILL.md"))
     assert agents_md.exists()
     assert len(skill_files) == 4
     assert "serialisable" in agents_md.read_text()
-    assert "process.dump" in (skills_dir / "create-yaml-config" / "SKILLS.md").read_text()
-    process_diagram_skill = skills_dir / "process-diagram" / "SKILLS.md"
-    run_process_skill = skills_dir / "run-process-scenario" / "SKILLS.md"
+    yaml_skill = skills_dir / "create-yaml-config" / "SKILL.md"
+    process_diagram_skill = skills_dir / "process-diagram" / "SKILL.md"
+    run_process_skill = skills_dir / "run-process-scenario" / "SKILL.md"
+    tune_skill = skills_dir / "configure-tune" / "SKILL.md"
+    assert yaml_skill.read_text().startswith("---\nname: create-yaml-config\n")
+    assert "process.dump" in yaml_skill.read_text()
     assert "plugboard process diagram" in process_diagram_skill.read_text()
     assert "plugboard process run" in run_process_skill.read_text()
-    assert "`tune` section" in (skills_dir / "configure-tune" / "SKILLS.md").read_text()
+    assert "`tune` section" in tune_skill.read_text()
+
+
+def test_cli_ai_init_github_style(tmp_path: Path) -> None:
+    """Tests the ai init command creates GitHub-style skills when requested."""
+    result = runner.invoke(app, ["ai", "init", "--style", "github", str(tmp_path)])
+    assert result.exit_code == 0
+    assert (tmp_path / "AGENTS.md").exists()
+    assert (tmp_path / ".github" / "skills" / "process-diagram" / "SKILL.md").exists()
 
 
 def test_cli_ai_init_already_exists(tmp_path: Path) -> None:
@@ -176,8 +187,8 @@ def test_cli_ai_init_already_exists(tmp_path: Path) -> None:
 
 
 def test_cli_ai_init_fails_when_skills_directory_exists(tmp_path: Path) -> None:
-    """Tests the ai init command fails when the skills directory already exists."""
-    (tmp_path / "skills").mkdir()
+    """Tests the ai init command fails when the selected skills directory already exists."""
+    (tmp_path / ".agents" / "skills").mkdir(parents=True)
     result = runner.invoke(app, ["ai", "init", str(tmp_path)])
     assert result.exit_code == 1
     assert "skills" in result.output
@@ -194,7 +205,7 @@ def test_cli_ai_init_default_directory() -> None:
             result = runner.invoke(app, ["ai", "init"])
             assert result.exit_code == 0
             assert (Path(tmpdir) / "AGENTS.md").exists()
-            assert (Path(tmpdir) / "skills" / "process-diagram" / "SKILLS.md").exists()
+            assert (Path(tmpdir) / ".agents" / "skills" / "process-diagram" / "SKILL.md").exists()
         finally:
             os.chdir(original_cwd)
 
@@ -208,7 +219,7 @@ def test_cli_ai_agents_template_is_packaged_file() -> None:
 
 def test_cli_ai_skills_templates_are_packaged_files() -> None:
     """Tests the skills templates are real package files rather than symlinks."""
-    skill_files = sorted(_SKILLS_DIR.glob("*/SKILLS.md"))
+    skill_files = sorted(_SKILLS_DIR.glob("*/SKILL.md"))
     assert skill_files
     for skill_file in skill_files:
         assert skill_file.exists()