feat(ai): add additive Agent Skills scaffolding to ai init

[Copilot]

Summary

Refines the packaged AI guidance for Plugboard model creation so agents favor YAML-friendly component arguments and decompose processes into components that mirror the real system. Extends plugboard ai init to scaffold AGENTS.md plus Agent Skills-compliant task-specific skills, with a --style option that installs them into the appropriate directory for Agents, GitHub, or Claude workflows, supports adding Plugboard skills into an existing skills directory when unrelated skills are already present, and now performs additive initialisation so missing AGENTS.md files or individual packaged skills can be installed without failing when other packaged AI files already exist. Includes a small follow-up refactor of the ai init CLI flow plus additional CLI coverage to keep the implementation within CI complexity limits and exercise the conflict/error-handling paths added by the feature work.

Changes

• AGENTS guidance

  • Reorganized plugboard/cli/ai/AGENTS.md around a clearer workflow: plan → implement → assemble → export/run.
  • Added explicit guidance to prefer serialisable component arguments so models can be represented in YAML.
  • Added explicit guidance to model real-world entities/stages as separate components rather than collapsing them into monolithic logic.
  • Updated skill references to point to style-specific Agent Skills directories and SKILL.md manifests.

• Packaged skills

  • Added Agent Skills-compliant SKILL.md templates with YAML frontmatter for:
    • creating YAML from a Python-defined process
    • generating diagrams with plugboard process diagram
    • running scenario-specific configs with plugboard process run
    • adding a tune section after eliciting tunable parameters from the user
  • Updated the YAML-related skills to validate generated or modified YAML against plugboard_schemas.ConfigSpec, which matches the schema used by the Plugboard CLI when loading configuration files.
  • Kept the skill content tool-agnostic and compatible with Claude, Gemini, Codex, and GitHub Copilot conventions.

• CLI scaffolding

  • Updated plugboard ai init to accept --style with:
    • agents → .agents/skills/ (default)
    • github → .github/skills/
    • claude → .claude/skills/
  • Continued to install AGENTS.md alongside the selected skills directory.
  • Changed skills installation so Plugboard skills can be added into an existing selected skills directory when it already contains other skills.
  • Changed initialisation to be additive: existing packaged AI files are reported and preserved, while any missing AGENTS.md file or packaged Plugboard skill directories are added instead of causing complete failure.
  • Preserved target validation for invalid paths such as packaged skill targets that already exist as non-directory entries.
  • Refactored the plugboard.cli.ai initialisation helpers without changing behaviour so the CLI implementation remains under the repository's xenon complexity thresholds.

• Docs and coverage

  • Updated user-facing docs to describe the new style-specific scaffolded layout and Agent Skills manifest format.
  • Documented that existing packaged AI files are preserved and missing packaged files are added on subsequent runs.
  • Expanded CLI tests to cover:
    • installation of AGENTS.md and .agents/skills/ by default
    • installation into .github/skills/ with --style github
    • merging Plugboard skills into an existing selected skills directory containing unrelated skills
    • additive installation when AGENTS.md already exists
    • additive installation when one of the packaged Plugboard skill directories already exists
    • packaged skill/template presence using SKILL.md
    • schema-validation guidance in the YAML-related skill manifests
    • failure when AGENTS.md exists as a directory
    • failure when the selected skills target exists as a non-directory path
    • failure when an individual packaged skill target already exists as a non-directory path

process.dump("model.yaml")
# then validate and use the generated config with:
# plugboard process validate model.yaml
# plugboard process diagram model.yaml
# plugboard process run model.yaml

[toby-coleman]

@copilot Modify the CLI command so that it takes a --style option, which may be claude, github or agents, and place the skills in one of these directories according to it:
.github/skills/
.agents/skills/
.claude/skills/
Default to agents.
Read https://agentskills.io/specification and make sure the skill files follow the standard, e.g. they should be named SKILL.md, include frontmatter etc.

[Copilot]

@copilot Modify the CLI command so that it takes a --style option, which may be claude, github or agents, and place the skills in one of these directories according to it:
.github/skills/
.ag...

Implemented in 8e1acf8. plugboard ai init now accepts --style (agents default, plus github and claude), installs skills into the corresponding .agents/skills/, .github/skills/, or .claude/skills/ directory, and the packaged manifests are now SKILL.md files with YAML frontmatter.

[toby-coleman]

@copilot two modifications:

• Allow the plugboard ai init command to add skills to an existing skills directory. For example if a skills directory exists with other skills in it, the command currently fails with Cannot initialise AI files
• Make sure that the skills related to YAML configs validate the YAML they create against the appropriate schema from plugboard-schemas. Examine the codebase to determine which schema to specify in the skill.

[Copilot]

@copilot two modifications:

• Allow the plugboard ai init command to add skills to an existing skills directory. For example if a skills directory exists with other skills in it, the command current...

Implemented in 4d75932. plugboard ai init now adds Plugboard skills into an existing selected skills directory as long as the packaged Plugboard skill folders are not already present, and the YAML-related skills now explicitly validate configs against plugboard_schemas.ConfigSpec (the schema used by the CLI when loading YAML).

[toby-coleman]

@copilot - modify so that missing AGENTS.md or individual skills can be added without complete failure. e.g. if AGENTS.md exists but one or more skill is missing, then report the existing files as is currently the case but add the missing skill.

[Copilot]

@copilot - modify so that missing AGENTS.md or individual skills can be added without complete failure. e.g. if AGENTS.md exists but one or more skill is missing, then report the existing files as is ...

Addressed in 46a2d74. plugboard ai init now treats existing AGENTS.md and packaged skill directories as already-installed, reports them, and still adds any missing packaged skills instead of failing the whole initialization.

[toby-coleman]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved in f8dea08.

[github-actions]

Benchmark comparison for 8eb94518 (base) vs f8dea08d (PR)

------------------------------------------------------------------------------------------------------------------ benchmark: 2 tests -----------------------------------------------------------------------------------------------------------------
Name (time in ms)                                                                         Min                 Max                Mean            StdDev              Median               IQR            Outliers     OPS            Rounds  Iterations
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_process_run (pr/.benchmarks/Linux-CPython-3.14-64bit/0001_pr)         527.3797 (1.0)      534.3697 (1.0)      531.2920 (1.0)      2.6819 (1.11)     531.5824 (1.0)      3.8040 (1.0)           2;0  1.8822 (1.0)           5           1
test_benchmark_process_run (main/.benchmarks/Linux-CPython-3.14-64bit/0001_base)     547.7748 (1.04)     553.1550 (1.04)     550.6701 (1.04)     2.4163 (1.0)      551.6694 (1.04)     4.2737 (1.12)          2;0  1.8160 (0.96)          5           1
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean

[codecov]

Codecov Report

❌ Patch coverage is 95.16129% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
plugboard/cli/ai/__init__.py	95.16%	1 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[toby-coleman]

@copilot fix the CI errors: xenon and codecov

[Copilot]

@copilot fix the CI errors: xenon and codecov

Fixed in a33fee5. I reduced the plugboard.cli.ai module complexity so xenon passes again and added focused CLI tests for the ai init conflict/error paths to improve patch coverage for Codecov.

[github-actions]

Benchmark comparison for 8eb94518 (base) vs a33fee57 (PR)

------------------------------------------------------------------------------------------------------------------ benchmark: 2 tests ------------------------------------------------------------------------------------------------------------------
Name (time in ms)                                                                         Min                 Max                Mean            StdDev              Median                IQR            Outliers     OPS            Rounds  Iterations
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_process_run (main/.benchmarks/Linux-CPython-3.14-64bit/0001_base)     527.9129 (1.0)      548.8108 (1.01)     535.0033 (1.0)      8.3673 (3.34)     532.0925 (1.0)      10.3562 (2.40)          1;0  1.8691 (1.0)           5           1
test_benchmark_process_run (pr/.benchmarks/Linux-CPython-3.14-64bit/0001_pr)         535.2962 (1.01)     541.2907 (1.0)      538.1203 (1.01)     2.5077 (1.0)      537.9376 (1.01)      4.3210 (1.0)           2;0  1.8583 (0.99)          5           1
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean