ma-agents 3.4.9 → 3.5.0

package/_bmad-output/implementation-artifacts/done/2-2-csharp-coding-standards-skill.md

@@ -0,0 +1,211 @@
+# Story 2.2: Create C# Best Practices Skill
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **C# engineer**,
+I want a C# coding standards and best practices skill available in ma-agents,
+So that my AI coding agent follows our organization's C# methodology consistently.
+
+## Acceptance Criteria
+
+1. **Given** the C# skill directory exists at `skills/csharp-best-practices/`
+   **When** the skill is listed via `npx ma-agents list`
+   **Then** it appears with description referencing C# standards and tags including "csharp"
+   **And** `skill.json` contains valid metadata including `applies_when` conditions for C#/.NET contexts
+
+2. **Given** the C# skill is installed to any supported agent
+   **When** the agent receives the skill content
+   **Then** it contains C# coding standards, .NET patterns, async/await best practices, and LINQ guidelines
+   **And** the content covers modern C# language features (C# 10+) applicable to .NET 6 through .NET 8+
+
+3. **Given** the skill follows the standard skill schema contract
+   **When** installed across multiple agents
+   **Then** the installed content is identical across all target agents (SKILL.md fallback, no agent-specific templates)
+   **And** content is language-focused, not agent-specific (FR36)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create skill directory and metadata (AC: #1)
+  - [x] 1.1: Create directory `skills/csharp-best-practices/`
+  - [x] 1.2: Create `skill.json` with all required fields (see skill.json Schema section below). Must include `applies_when` array for skill discovery and `always_load: true` (this is the only C# skill — it must auto-load in C# contexts).
+  - [x] 1.3: Verify `npx ma-agents list` shows the new skill with correct metadata
+- [x] Task 2: Author SKILL.md content (AC: #2)
+  - [x] 2.1: Write C# coding standards covering: naming conventions (PascalCase types/methods, camelCase locals/params, _camelCase private fields), code organization (namespace per folder, one type per file). Target practical density — prioritize high-value rules over exhaustive coverage. If content naturally exceeds 500 lines, use `references/` directory for supplementary material.
+  - [x] 2.2: Include async/await best practices: async all the way, avoid async void (except event handlers), ConfigureAwait guidance, cancellation token propagation, ValueTask vs Task guidance
+  - [x] 2.3: Include LINQ guidelines: when to use query vs method syntax, deferred execution awareness, materialization points, performance considerations for large collections
+  - [x] 2.4: Include modern C# language features (C# 10/11/12): primary constructors, collection expressions, raw string literals, required members, file-scoped types, global usings, nullable reference types (NRT) enforcement. Note: these features span .NET 6–8 — scope is "modern C#" not strictly ".NET 8 only."
+  - [x] 2.5: Include error handling patterns: exception hierarchy, Result pattern, problem details for APIs, global exception handling middleware
+  - [x] 2.6: Include dependency injection overview: constructor injection, service lifetimes (Singleton/Scoped/Transient). Keep to language-level patterns only — defer framework-specific DI patterns (IOptions, keyed services, middleware) to a future `csharp-aspnet-patterns` skill to avoid overlap.
+  - [x] 2.7: Include testing patterns: Arrange-Act-Assert structure, framework-agnostic conventions. Present xUnit as one common choice but acknowledge MSTest and NUnit as alternatives. Avoid prescribing specific assertion or mocking libraries — mention FluentAssertions, NSubstitute, Moq as popular options without mandating them.
+  - [x] 2.8: Optionally create `examples/` directory with representative code samples, consistent with peer language skills
+- [x] Task 3: Verify installation across agents (AC: #3)
+  - [x] 3.1: Install to at least 2 different agents (e.g., claude-code and cursor)
+  - [x] 3.2: Verify installed content is identical across agents (SKILL.md fallback is the only path)
+  - [x] 3.3: Verify `generateSkillsManifest()` produces correct MANIFEST.yaml entries — check that `applies_when` conditions and `always_load` flag are present in the generated manifest
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Skill schema contract:** Every skill MUST have `skill.json` (metadata SSoT) + `SKILL.md` (canonical content). Optional directories: `examples/`, `references/`, `scripts/`, `hooks/`, `assets/`. [Source: architecture.md#Data-Architecture]
+- **Directory naming:** `kebab-case` for skill directories [Source: architecture.md#Naming-Patterns]
+- **No installer changes needed:** Adding a new skill requires ONLY the skill package files — the installer discovers skills by scanning the `skills/` directory via `listSkills()`. [Source: architecture.md#Extensibility-Model, NFR14]
+- **Template resolution:** `<agent-name>.md` (highest) -> `generic.md` -> `SKILL.md` (lowest/fallback). Templates are flat files at the skill root — there is NO `templates/` subdirectory. For this skill, `SKILL.md` alone is sufficient.
+
+### Greenfield — No Existing C# Skills
+
+Unlike C++ (6 existing domain skills) and Python (2 existing domain skills), **no C# skills currently exist** in the library. This skill is the first C# entry.
+
+**Implications of being the only C# skill:**
+- It must be self-contained — no sibling skills to cross-reference. Content should be more detailed than the C++ umbrella skill which can defer to 6 companions.
+- `always_load: true` is important — without it, and without other C# skills, there is no C# guidance unless the developer explicitly requests it.
+- Scope boundaries should be drawn clearly for future skills. This skill covers **language-level** patterns. Framework-specific patterns (ASP.NET Core middleware, EF Core, Blazor, etc.) should be deferred to future skills like `csharp-aspnet-patterns` or `csharp-ef-core`.
+
+### skill.json Schema
+
+Follow the pattern from existing skills. The `applies_when` field is **critical** — it tells the manifest generator and planning instruction when to load this skill:
+```json
+{
+  "name": "C# Best Practices",
+  "description": "Comprehensive C# coding standards covering modern C# (C# 10-12), async/await, LINQ, dependency injection basics, nullable reference types, and testing conventions.",
+  "version": "1.0.0",
+  "author": "ma-agents",
+  "tags": ["csharp", "c#", "dotnet", ".net", "coding-standards", "best-practices", "net8"],
+  "applies_when": [
+    "writing c# code",
+    "creating new c# files or classes",
+    "reviewing c# code style or conventions",
+    "working with .net projects",
+    "setting up a c# project"
+  ],
+  "always_load": true
+}
+```
+
+**Note on `category` field:** Omitted — no existing skill uses it, and `listSkills()` doesn't read or filter by it. Can be backfilled if category support is added later.
+
+**Note on `always_load: true`:** As the only C# skill in the library, this must auto-load. Without it, AI agents have no C# guidance unless the developer knows to request it by name. This matches the pattern of other "primary" language skills like `cmake-best-practices` and `cpp-modern-composition`.
+
+### SKILL.md Content Pattern
+
+Follow the **policy-based pattern** used by existing language skills:
+- Lead with language context and scope — specify "modern C# (C# 10+)" rather than ".NET 8+" to match the actual feature coverage
+- Use numbered policies with **Rule** -> **Action** format
+- Include tables for naming convention mappings (see Naming Convention Table below)
+- Consider creating an `examples/` directory with representative code samples, consistent with peer language skills
+- Target practical density — if content exceeds 500 lines, split supplementary material to `references/`
+- **No YAML frontmatter** — metadata comes from skill.json only
+
+### Modern C# Coverage Priorities
+
+The skill covers **modern C# language features** across recent .NET versions. The scope is "modern C#" (C# 10+), not strictly ".NET 8 only":
+
+**C# 12 (.NET 8):** Primary constructors, collection expressions (`[1, 2, 3]`), default lambda parameters, alias any type, inline arrays
+**C# 11 (.NET 7):** Raw string literals, required members, file-scoped types, generic math, list patterns
+**C# 10 (.NET 6):** Global usings, file-scoped namespaces, record structs, extended property patterns
+**Foundational:** Nullable reference types (NRT), pattern matching, records, init-only properties, top-level statements
+
+**Language-level framework patterns (include):** System.Text.Json, IHttpClientFactory, basic DI (constructor injection, service lifetimes)
+**Framework-specific patterns (defer to future skills):** Minimal APIs, middleware pipelines, IOptions/IOptionsSnapshot, Health Checks, OpenTelemetry, EF Core — these belong in a future `csharp-aspnet-patterns` or `csharp-ef-core` skill
+
+### Naming Convention Table
+
+Include a comprehensive naming table — this is the highest-value section for AI agents:
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Namespace | PascalCase, match folder | `MyApp.Services` |
+| Class/Struct/Record | PascalCase | `CustomerService` |
+| Interface | IPascalCase | `ICustomerService` |
+| Method | PascalCase | `GetCustomerAsync` |
+| Property | PascalCase | `FirstName` |
+| Local variable | camelCase | `customerCount` |
+| Parameter | camelCase | `customerId` |
+| Private field | _camelCase | `_logger` |
+| Constant | PascalCase | `MaxRetryCount` |
+| Enum | PascalCase (singular) | `OrderStatus` |
+| Async method | suffix `Async` | `SaveAsync` |
+
+### Testing Patterns — Framework Agnosticism
+
+Task 2.7 covers testing patterns. This is an area where opinionated prescriptions cause problems — many C# teams use different frameworks. The SKILL.md should:
+- Present **Arrange-Act-Assert** as the universal pattern
+- Mention xUnit, NUnit, and MSTest as the three major frameworks without mandating one
+- Reference FluentAssertions, Shouldly, NSubstitute, Moq as popular options, not requirements
+- Focus on test structure, naming conventions, and practices that are framework-agnostic
+
+### Critical Guardrails
+
+- **No installer code changes** — only skill package files [Source: architecture.md, NFR14]
+- **kebab-case** directory name: `csharp-best-practices` [Source: architecture.md#Naming-Patterns]
+- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
+- **No emoji** in SKILL.md content [Source: architecture.md#Format-Patterns]
+- **Cross-agent equivalence** — content must be language-focused, not agent-specific (FR36)
+- **Must include `applies_when`** in skill.json — without it, the skill won't appear in generated MANIFEST.yaml with load conditions, making it invisible to automatic skill selection
+- **Language vs. framework boundary** — keep DI, error handling, and testing content at the language level. Defer ASP.NET Core middleware, EF Core, Blazor patterns to future skills.
+
+### Project Structure Notes
+
+- New directory: `skills/csharp-best-practices/`
+- New files: `skill.json`, `SKILL.md`
+- Optional: `examples/` directory for representative code samples
+- Optional: `references/` directory if content exceeds 500 lines
+- No changes to any existing files or modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-2] — Story 2.2 definition and acceptance criteria
+- [Source: _bmad-output/planning-artifacts/prd.md#FR36] — FR36: Functionally equivalent behavior across agents
+- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
+- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority
+- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
+- [Source: skills/python-security-skill/] — Representative policy-based skill pattern (includes applies_when)
+- [Source: skills/cpp-memory-handling/] — Representative language skill structure (includes applies_when, examples/)
+- [Source: lib/installer.js `function listSkills`] — Skill discovery mechanism
+- [Source: lib/installer.js `function generateSkillsManifest`] — MANIFEST.yaml generation (consumes applies_when, always_load)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — implementation was straightforward skill package authoring.
+
+### Completion Notes List
+
+- Created `skills/csharp-best-practices/skill.json` with all required fields: name, description, version, author, tags (including "csharp"), applies_when (5 conditions), always_load: true.
+- Created `skills/csharp-best-practices/SKILL.md` covering: naming conventions table, code organization, nullable reference types, modern C# features (primary constructors, collection expressions, raw strings, pattern matching, records and record structs, file-scoped types), async/await, LINQ, error handling (Result pattern + exception hierarchy), dependency injection (service lifetimes), and testing (AAA pattern, framework-agnostic).
+- Skipped `examples/` directory (task 2.8 was optional; SKILL.md code blocks are sufficient for AI agent consumption).
+- Task 2.5 (error handling): Global exception handling middleware is explicitly deferred to a future `csharp-aspnet-patterns` skill — it is an ASP.NET Core framework-specific pattern, not a language-level concern. The language-level obligation (ensuring exceptions carry sufficient data to produce a ProblemDetails response) is covered in Section 7.
+- Installed to claude-code agent: `.claude/skills/csharp-best-practices/SKILL.md` and updated MANIFEST.yaml.
+- Installed to cursor agent: `.cursor/skills/csharp-best-practices/SKILL.md` and updated MANIFEST.yaml.
+- Verified installed content is byte-for-byte identical across both agents (SKILL.md fallback path only).
+- Verified generated MANIFEST.yaml entries include `applies_when` conditions and `always_load: true`.
+- All 9 existing regression tests passed.
+- **Code review fixes applied (2026-03-19):** Added Section 4.6 (file-scoped types, C# 11 `file` modifier); expanded Section 4.5 to cover `record struct` and `readonly record struct`; replaced EF Core `FirstOrDefaultAsync` in async example with framework-agnostic `_repository.GetByIdAsync`; replaced ASP.NET Core `builder.Services` in DI example with `IServiceCollection`; clarified Section 7 middleware deferral boundary.
+
+### File List
+
+- skills/csharp-best-practices/skill.json (new)
+- skills/csharp-best-practices/SKILL.md (new)
+- .claude/skills/csharp-best-practices/SKILL.md (new — installed)
+- .claude/skills/MANIFEST.yaml (modified — new entry added)
+- .claude/CLAUDE.md (modified — planning instruction updated)
+- .cursor/skills/csharp-best-practices/SKILL.md (new — installed)
+- .cursor/skills/MANIFEST.yaml (modified — new entry added)
+- .cursor/cursor.md (modified — planning instruction updated)
+- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — status updated)
+- _bmad-output/implementation-artifacts/2-2-csharp-coding-standards-skill.md (modified — tasks checked, status updated)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 2.2 — Created C# Best Practices skill package (`skill.json` + `SKILL.md`), installed to claude-code and cursor agents, verified cross-agent content equivalence and MANIFEST.yaml generation.
+- 2026-03-19: Code review fixes — Added file-scoped types (§4.6), record struct guidance (§4.5), replaced framework-coupled code examples in §5 and §8, documented middleware deferral in §7 and completion notes.

package/_bmad-output/implementation-artifacts/done/2-3-python-coding-standards-skill.md

@@ -0,0 +1,189 @@
+# Story 2.3: Create Python Best Practices Skill
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Python engineer**,
+I want a Python coding standards and best practices skill available in ma-agents,
+So that my AI coding agent follows our organization's Python methodology consistently.
+
+## Acceptance Criteria
+
+1. **Given** the Python skill directory exists at `skills/python-best-practices/`
+   **When** the skill is listed via `npx ma-agents list`
+   **Then** it appears with category "language" and description referencing Python standards
+
+2. **Given** the Python skill is installed to any supported agent
+   **When** the agent receives the skill content
+   **Then** it contains Python coding standards, PEP 8 conventions, type hinting patterns, and packaging best practices
+   **And** the content covers Python 3.10+ modern patterns
+
+3. **Given** all three language skills (C++, C#, Python) are installed
+   **When** the manifest is checked via `npx ma-agents status`
+   **Then** all three appear with correct versions and installation status per agent
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create skill directory and metadata (AC: #1)
+  - [x] 1.1: Create directory `skills/python-best-practices/`
+  - [x] 1.2: Create `skill.json` with: name "Python Best Practices", version "1.0.0", category "language", description referencing Python coding standards for 3.10+, author "ma-agents", tags ["python", "coding-standards", "best-practices", "pep8", "type-hints"], always_load false
+  - [x] 1.3: Verify `npx ma-agents list` shows the new skill with correct metadata
+- [x] Task 2: Author SKILL.md content (AC: #2)
+  - [x] 2.1: Write comprehensive Python coding standards covering: PEP 8 naming conventions (snake_case functions/variables, PascalCase classes, UPPER_SNAKE constants), code organization (module structure, `__init__.py` patterns, `__all__` exports)
+  - [x] 2.2: Include type hinting patterns: function annotations, variable annotations, generics (`list[str]` not `List[str]` for 3.10+), `TypeAlias`, `TypeVar`, `Protocol`, `ParamSpec`, `TypeGuard`, `Self` (3.11), `type` statement (3.12)
+  - [x] 2.3: Include modern Python patterns: structural pattern matching (`match/case` 3.10), exception groups and `except*` (3.11), f-string improvements (3.12), `__slots__` usage, dataclasses vs attrs vs Pydantic guidance, walrus operator (`:=`)
+  - [x] 2.4: Include packaging best practices: `pyproject.toml` (not setup.py), dependency management (pip-tools, poetry, uv), virtual environments, `src/` layout convention
+  - [x] 2.5: Include async patterns: `asyncio` conventions, `async for`/`async with`, `TaskGroup` (3.11), structured concurrency, avoid mixing sync and async
+  - [x] 2.6: Cross-reference existing Python skills where they provide deeper coverage (see Dev Notes)
+- [x] Task 3: Verify installation across agents and manifest status (AC: #2, #3)
+  - [x] 3.1: Install to at least 2 different agents (e.g., claude-code and cursor)
+  - [x] 3.2: Verify SKILL.md fallback works when no agent-specific template exists
+  - [x] 3.3: Install all 3 language skills (cpp-best-practices, csharp-best-practices, python-best-practices) and verify `npx ma-agents status` shows all three with correct versions
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Skill schema contract:** Every skill MUST have `skill.json` (metadata SSoT) + `SKILL.md` (canonical content). No other files are required. [Source: architecture.md#Data-Architecture]
+- **Directory naming:** `kebab-case` for skill directories [Source: architecture.md#Naming-Patterns]
+- **No installer changes needed:** Adding a new skill requires ONLY the skill package files — the installer discovers skills by scanning the directory. [Source: architecture.md#Extensibility-Model, NFR14]
+- **Template resolution:** `templates/<agent-name>.md` -> `templates/generic.md` -> `SKILL.md` (fallback). For this skill, `SKILL.md` alone is sufficient.
+
+### Relationship to Existing Python Skills
+
+2 domain-specific Python skills already exist in the library:
+
+| Existing Skill | Focus | Relationship |
+|---------------|-------|-------------|
+| `python-security-skill` | OWASP 2025 aligned security (always_load: true) | Deep-dive on security — cross-reference from best-practices |
+| `python-dependency-mgmt` | Dependency/supply chain security | Deep-dive on dependency security — cross-reference |
+
+**This skill is the umbrella** — it covers broad Python coding standards, type hinting, modern patterns, and packaging, while referencing the security-focused skills for deeper coverage. It should NOT duplicate content from existing skills. Use cross-references like:
+```markdown
+> For Python security best practices (OWASP 2025), see the `python-security-skill`.
+> For dependency security and supply chain protection, see the `python-dependency-mgmt` skill.
+```
+
+### skill.json Schema
+
+```json
+{
+  "name": "Python Best Practices",
+  "description": "Comprehensive Python coding standards covering PEP 8 conventions, type hinting (3.10+), modern patterns (match/case, exception groups), async, and packaging best practices. Cross-references security-focused Python skills.",
+  "version": "1.0.0",
+  "category": "language",
+  "author": "ma-agents",
+  "tags": ["python", "coding-standards", "best-practices", "pep8", "type-hints", "python3.10", "python3.11", "python3.12"],
+  "always_load": false
+}
+```
+
+### SKILL.md Content Pattern
+
+Follow the **policy-based pattern** used by existing Python skills (e.g., `python-security-skill/SKILL.md`):
+- Lead with language context and Python version scope (3.10+)
+- Use numbered policies with **Rule** -> **Action** format
+- Include tables for naming convention mappings and modern pattern guidance
+- Cross-reference sibling Python skills
+- Keep under 500 lines — split to `references/` if needed
+- **No YAML frontmatter** — metadata comes from skill.json only
+
+### Python 3.10+ Coverage Priorities
+
+The skill must cover **Python 3.10+ modern patterns** per AC #2:
+
+**Python 3.10:** Structural pattern matching (`match/case`), `ParamSpec`, `TypeAlias`, union types with `X | Y` syntax, `TypeGuard`
+**Python 3.11:** Exception groups (`ExceptionGroup`, `except*`), `Self` type, `TaskGroup` for structured concurrency, `tomllib`, `StrEnum`
+**Python 3.12:** `type` statement for type aliases, f-string improvements (nested quotes, backslashes), `@override` decorator, per-interpreter GIL (awareness)
+**Python 3.13 (awareness):** Free-threaded mode (`--disable-gil`), improved error messages — mention as forward-looking but don't make it a requirement
+
+### Type Hinting Evolution Table
+
+Include a version-aware type hinting table — high value for AI agents:
+
+| Pattern | Old (pre-3.10) | Modern (3.10+) |
+|---------|---------------|----------------|
+| Union types | `Union[str, int]` | `str \| int` |
+| Optional | `Optional[str]` | `str \| None` |
+| List type | `List[str]` | `list[str]` |
+| Dict type | `Dict[str, int]` | `dict[str, int]` |
+| Tuple type | `Tuple[str, ...]` | `tuple[str, ...]` |
+| Type alias | `MyType = list[str]` | `type MyType = list[str]` (3.12) |
+
+### Packaging Guidance: Modern Stack
+
+The packaging section should recommend the modern toolchain:
+- **`pyproject.toml`** over `setup.py`/`setup.cfg` — PEP 621 compliant
+- **`uv`** as the recommended fast package manager (Astral, Rust-based)
+- **`src/` layout** as the default project structure
+- **`ruff`** for linting and formatting (replaces flake8 + black + isort)
+- **`mypy` or `pyright`** for type checking
+
+### Critical Guardrails
+
+- **No installer code changes** — only skill package files [Source: architecture.md, NFR14]
+- **kebab-case** directory name: `python-best-practices` [Source: architecture.md#Naming-Patterns]
+- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
+- **No emoji** in SKILL.md content [Source: architecture.md#Format-Patterns]
+- **Do not duplicate** content from existing Python skills — cross-reference instead
+- **Cross-agent equivalence** — content must be language-focused, not agent-specific (FR36)
+
+### AC #3: Cross-Skill Manifest Verification
+
+This story's AC #3 is a cross-cutting acceptance criterion that validates all 3 Epic 2 skills together. It should be tested AFTER stories 2-1 and 2-2 are also complete. If implementing stories in order, this AC can only be fully verified as the last step of story 2-3. If stories are implemented in parallel, coordinate manifest verification at the end.
+
+### Project Structure Notes
+
+- New directory: `skills/python-best-practices/`
+- New files: `skill.json`, `SKILL.md`
+- Optional: `references/` directory if content exceeds 500 lines
+- No changes to any existing files or modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-2] — Story 2.3 definition and acceptance criteria
+- [Source: _bmad-output/planning-artifacts/prd.md#FR36] — FR36: Functionally equivalent behavior across agents
+- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
+- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority
+- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
+- [Source: skills/python-security-skill/] — Existing Python security skill (cross-reference target)
+- [Source: skills/python-dependency-mgmt/] — Existing Python dependency skill (cross-reference target)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+No debug issues encountered. Implementation was straightforward: two files only, no installer changes.
+
+### Completion Notes List
+
+- Created `skills/python-best-practices/skill.json` with correct metadata matching schema from Dev Notes: category "language", always_load false, 8 tags covering python/pep8/type-hints and version tags.
+- Created `skills/python-best-practices/SKILL.md` (~350 lines, under 500-line limit) covering all 6 subtask areas: PEP 8 naming (section 1), code organization (section 2), type hinting with version table and advanced constructs (section 3), modern patterns — match/case, except*, f-strings, walrus, __slots__, dataclasses guidance (section 4), async patterns with TaskGroup (section 5), packaging with pyproject.toml + uv + ruff + src/ layout (section 6), 3.13 forward-looking awareness (section 7), and cross-references to sibling Python skills.
+- SKILL.md uses no emoji (per architecture guardrail), no YAML frontmatter, and follows the policy-based Rule/Action pattern from existing Python skills. Installed copies have installer-injected frontmatter (systemic behavior — all peer skills have it too).
+- Verified `npx ma-agents list` shows skill with correct description (AC #1).
+- Installed to claude-code and cursor agents; SKILL.md fallback confirmed (no agent-specific templates needed) (AC #2, 3.1, 3.2).
+- Verified `npx ma-agents status` shows all three language skills (cpp-best-practices, csharp-best-practices, python-best-practices) at v1.0.0 installed (AC #3).
+
+### File List
+
+- `skills/python-best-practices/skill.json` (new)
+- `skills/python-best-practices/SKILL.md` (new)
+- `.claude/skills/python-best-practices/SKILL.md` (new — installed artifact)
+- `.claude/skills/MANIFEST.yaml` (modified — updated by installer)
+- `.claude/CLAUDE.md` (modified — updated by installer)
+- `.cursor/skills/python-best-practices/SKILL.md` (new — installed artifact)
+- `.cursor/skills/MANIFEST.yaml` (modified — updated by installer)
+- `.cursor/cursor.md` (modified — updated by installer)
+
+## Change Log
+
+- 2026-03-19: Story 2.3 implemented — created Python Best Practices skill package (`skill.json` + `SKILL.md`), installed to claude-code and cursor agents, verified all 3 Epic 2 language skills in `npx ma-agents status`.
+- 2026-03-19: Code review fixes: async example bug (H2 — `open(path)` replaced with `Path(path).read_text` in `asyncio.to_thread`), MANIFEST `always_load: false` added to both agent MANIFESTs (H1), M3 coverage additions (`StrEnum`, `tomllib`, `@override` in new section 4.7), L1 virtual environments section added (section 6.4, `uv venv` / `.venv`), L2 walrus operator comment fixed ("Without walrus" → "With walrus — single call"). Installed copies synced. M1 completion note updated to reflect installer-injected frontmatter as systemic behavior.

package/_bmad-output/implementation-artifacts/done/3-1-skill-scaffolding-tool.md

@@ -0,0 +1,184 @@
+# Story 3.1: Skill Scaffolding Command
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want to run `npx ma-agents create-skill <skill-name>` to generate a new skill directory with all required files,
+So that I can author new skills quickly without manually creating the directory structure.
+
+## Acceptance Criteria
+
+1. **Given** the user runs `npx ma-agents create-skill my-new-skill`
+   **When** the command executes
+   **Then** a directory `skills/my-new-skill/` is created with:
+   - `skill.json` populated with name, version "1.0.0", empty description, default category, empty tags, `always_load: false`
+   - `SKILL.md` with a template structure including placeholder content sections
+   - `templates/` directory (empty, ready for agent-specific templates)
+   - `references/` directory (empty)
+   - `assets/` directory (empty)
+
+2. **Given** a skill with the same name already exists
+   **When** the create-skill command is run
+   **Then** the command fails with an error message and does not overwrite the existing skill
+   **And** a hint suggests using a different name or removing the existing skill first
+
+3. **Given** the skill name contains invalid characters (spaces, uppercase, special chars)
+   **When** the create-skill command is run
+   **Then** the command fails with an error explaining kebab-case naming requirement
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `create-skill` command to CLI router (AC: #1, #2, #3)
+  - [x] 1.1: Add `create-skill` to the command routing in `bin/cli.js` (search: command routing logic, likely a switch/if-else block handling `install`, `list`, `status`, `uninstall`)
+  - [x] 1.2: Create handler function `handleCreateSkill(args)` in `bin/cli.js` or a new `lib/skill-authoring.js` module (see Dev Notes on module placement)
+  - [x] 1.3: Add `create-skill` to help text (search: `console.log.*Usage`)
+- [x] Task 2: Implement name validation (AC: #3)
+  - [x] 2.1: Validate skill name matches kebab-case pattern: `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
+  - [x] 2.2: On invalid name: print `Error: Skill name must be kebab-case (lowercase letters, numbers, hyphens)` / `Hint: Example: my-new-skill, python-linting, api-security`
+  - [x] 2.3: Exit with code 1 on validation failure
+- [x] Task 3: Implement duplicate detection (AC: #2)
+  - [x] 3.1: Check if `skills/<skill-name>/` directory already exists
+  - [x] 3.2: On duplicate: print `Error: Skill '<skill-name>' already exists at skills/<skill-name>/` / `Hint: Choose a different name or remove the existing skill first`
+  - [x] 3.3: Exit with code 1 on duplicate
+- [x] Task 4: Generate skill directory and files (AC: #1)
+  - [x] 4.1: Create `skills/<skill-name>/` directory
+  - [x] 4.2: Generate `skill.json` with template values:
+    ```json
+    {
+      "name": "<Skill Name from kebab>",
+      "description": "",
+      "version": "1.0.0",
+      "category": "workflow",
+      "author": "ma-agents",
+      "tags": [],
+      "always_load": false
+    }
+    ```
+    Convert kebab-case to Title Case for the name field (e.g., `my-new-skill` -> `My New Skill`)
+  - [x] 4.3: Generate `SKILL.md` with template structure (see Dev Notes for template content)
+  - [x] 4.4: Create empty directories: `templates/`, `references/`, `assets/`
+  - [x] 4.5: Print success message: `Skill '<skill-name>' created at skills/<skill-name>/`
+  - [x] 4.6: Print next steps hint: `  Next: Edit skill.json and SKILL.md to add your skill content`
+- [x] Task 5: Test the command
+  - [x] 5.1: Run `npx ma-agents create-skill test-skill` and verify all files/dirs created
+  - [x] 5.2: Run `npx ma-agents create-skill test-skill` again and verify duplicate error
+  - [x] 5.3: Run `npx ma-agents create-skill InvalidName` and verify kebab-case error
+  - [x] 5.4: Run `npx ma-agents list` and verify new skill appears
+  - [x] 5.5: Clean up test skill directory after testing
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Command routing:** New commands are added to the CLI router in `bin/cli.js`. The router dispatches to handler functions. [Source: architecture.md#Module-Boundaries]
+- **Module placement decision:** This command primarily creates files on disk. Two options:
+  1. **Inline in cli.js** — if the logic is <50 lines, keep it in cli.js as a handler function (simpler, follows existing pattern for simple commands)
+  2. **New module `lib/skill-authoring.js`** — if the logic grows beyond scaffolding (validation, test-install in stories 3-2/3-3), create a new module. The 4-module architecture allows new modules when genuinely needed. [Source: architecture.md#Enforcement-Guidelines]
+  **Recommendation:** Create `lib/skill-authoring.js` since Epic 3 has multiple skill authoring commands that share context. This keeps cli.js as a thin router.
+- **File operations:** Use `fs.mkdirSync` with `{ recursive: true }` for directory creation. Use `path.join()` for all paths. [Source: architecture.md#Enforcement-Guidelines]
+- **No new dependencies:** Use Node.js built-in `fs` and `path` only.
+
+### SKILL.md Template Content
+
+The generated SKILL.md should provide a useful starting structure:
+
+```markdown
+# <Skill Name>
+
+<Brief description of what this skill does and when it applies.>
+
+## Policies
+
+### 1. <First Policy>
+
+**Rule:** <What the agent must do or not do>
+
+**Action:**
+- <Specific instruction>
+- <Specific instruction>
+
+### 2. <Second Policy>
+
+**Rule:** <What the agent must do or not do>
+
+**Action:**
+- <Specific instruction>
+
+## References
+
+- <Link to any supporting documents in references/ directory>
+```
+
+This matches the policy-based pattern used by existing skills (e.g., `cpp-memory-handling`, `python-security-skill`).
+
+### skill.json Default Category
+
+The architecture specifies valid categories: `security|architecture|testing|documentation|workflow|language`. Default to `"workflow"` as the most generic category. The author will change it to the appropriate category.
+
+### Kebab-to-Title Conversion
+
+For the `name` field in skill.json, convert kebab-case to Title Case:
+- `my-new-skill` -> `My New Skill`
+- `python-best-practices` -> `Python Best Practices`
+- `api-security` -> `Api Security`
+
+Simple implementation: `name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ')`
+
+### Critical Guardrails
+
+- **Use `path.join()` for all file paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+- **Error format:** `Error: <what>` then `  Hint: <how to fix>` [Source: architecture.md#Format-Patterns]
+- **Console output:** plain text, chalk colors, no emoji [Source: architecture.md#Format-Patterns]
+- **File naming:** `kebab-case` for directories, `snake_case` for skill.json keys [Source: architecture.md#Naming-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js` (add command route)
+- Files to create: `lib/skill-authoring.js` (new module for skill authoring commands)
+- No changes to existing skills, installer, or agents modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-3] — Story 3.1 definition
+- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
+- [Source: _bmad-output/planning-artifacts/architecture.md#Skill-Directory-Structure] — Mandatory skill structure
+- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
+- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
+- [Source: _bmad-output/planning-artifacts/architecture.md#Format-Patterns] — Console output and error format
+- [Source: skills/skill-creator/SKILL.md] — Existing skill-creator skill (reference for authoring guidance)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — implementation was straightforward.
+
+### Completion Notes List
+
+- Created `lib/skill-authoring.js` with `validateSkillName`, `createSkill`, `handleCreateSkill`, `kebabToTitleCase` exports
+- Added `create-skill` command routing to `bin/cli.js` switch statement
+- Added `create-skill` to help text in `showHelp()`
+- Created `test/skill-authoring.test.js` with 14 tests: 6 unit tests for `validateSkillName`, 8 integration CLI tests covering all ACs
+- All 14 new tests pass; all 58 existing regression tests pass (no regressions)
+- Skill directory structure created: root dir, skill.json, SKILL.md, templates/, references/, assets/
+- kebab-to-title-case conversion: `my-new-skill` → `My New Skill`
+- Error format follows architecture: `Error: <what>` + `  Hint: <how to fix>`
+
+### File List
+
+- `lib/skill-authoring.js` (new)
+- `bin/cli.js` (modified — added import, create-skill case, help text)
+- `test/skill-authoring.test.js` (new)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 3.1 — create-skill scaffolding command with name validation, duplicate detection, file generation, and tests