skills

Author: KSemenenko

.github/workflows/jekyll-gh-pages.yml

@@ -136,6 +136,27 @@ jobs:
                   data[key.strip()] = value.strip().strip("\"'")
               return data
 
+          def replace_marker_block(
+              text: str,
+              begin_marker: str,
+              end_marker: str,
+              replacement_lines: list[str],
+          ) -> str:
+              begin_idx = text.find(begin_marker)
+              if begin_idx == -1:
+                  raise SystemExit(f"Missing marker: {begin_marker}")
+
+              begin_line_end = text.find("\n", begin_idx)
+              if begin_line_end == -1:
+                  raise SystemExit(f"Broken marker line: {begin_marker}")
+
+              end_idx = text.find(end_marker, begin_line_end + 1)
+              if end_idx == -1:
+                  raise SystemExit(f"Missing marker: {end_marker}")
+
+              replacement = "\n".join(replacement_lines).rstrip()
+              return text[: begin_line_end + 1] + replacement + "\n" + text[end_idx:]
+
           skills: list[dict[str, str]] = []
           for skill_md in sorted((repo / "skills").glob("*/SKILL.md")):
               skill_dir = skill_md.parent
@@ -223,21 +244,67 @@ jobs:
               "\n".join(skills_page_lines) + "\n",
               encoding="utf-8",
           )
-          PY
 
-      - name: Copy TUTORIAL to github-pages
-        run: |
-          cat > github-pages/tutorial.md << 'EOF'
-          ---
-          layout: default
-          title: Tutorial
-          description: Step-by-step tutorial for bootstrapping an MCAF v1.2 repository through URLs, bootstrap templates, and direct GitHub skill folders.
-          keywords: MCAF tutorial, AGENTS.md setup, skill-first install, AI coding bootstrap, Codex skills, Claude Code skills
-          nav_order: 3
-          ---
-          EOF
-          sed -i 's/^          //' github-pages/tutorial.md
-          cat TUTORIAL.md >> github-pages/tutorial.md
+          dotnet_optional_exclude = {
+              "mcaf-dotnet-features",
+              "mcaf-dotnet-quality-ci",
+              "mcaf-dotnet-complexity",
+              "mcaf-dotnet-xunit",
+              "mcaf-dotnet-tunit",
+              "mcaf-dotnet-mstest",
+          }
+          dotnet_optional = sorted(
+              skill["name"]
+              for skill in skills
+              if skill["name"].startswith("mcaf-dotnet-")
+              and skill["name"] not in dotnet_optional_exclude
+          )
+          dotnet_optional_lines = (
+              [f"- `{skill_name}`" for skill_name in dotnet_optional]
+              if dotnet_optional
+              else ["- _No optional .NET skills found._"]
+          )
+
+          all_skills_lines = [
+              (
+                  f"- `{skill['name']}` — "
+                  f"[Folder]({skill['folder_url']}), "
+                  f"[Raw SKILL]({skill['skill_md_url']})"
+              )
+              for skill in skills
+          ]
+
+          tutorial_body = (repo / "TUTORIAL.md").read_text(encoding="utf-8")
+          tutorial_body = replace_marker_block(
+              tutorial_body,
+              "<!-- MCAF:DOTNET-OPTIONAL-SKILLS-BEGIN -->",
+              "<!-- MCAF:DOTNET-OPTIONAL-SKILLS-END -->",
+              dotnet_optional_lines,
+          )
+          tutorial_body = replace_marker_block(
+              tutorial_body,
+              "<!-- MCAF:ALL-SKILLS-BEGIN -->",
+              "<!-- MCAF:ALL-SKILLS-END -->",
+              all_skills_lines,
+          )
+
+          tutorial_frontmatter = "\n".join(
+              [
+                  "---",
+                  "layout: default",
+                  "title: Tutorial",
+                  "description: Step-by-step tutorial for bootstrapping an MCAF v1.2 repository through URLs, bootstrap templates, and direct GitHub skill folders.",
+                  "keywords: MCAF tutorial, AGENTS.md setup, skill-first install, AI coding bootstrap, Codex skills, Claude Code skills",
+                  "nav_order: 3",
+                  "---",
+                  "",
+              ]
+          )
+          (repo / "github-pages" / "tutorial.md").write_text(
+              tutorial_frontmatter + tutorial_body.rstrip() + "\n",
+              encoding="utf-8",
+          )
+          PY
 
       - name: Copy CREDITS to github-pages
         run: |

TUTORIAL.md

@@ -12,13 +12,32 @@ The install path is URL-first and simple:
 
 ---
 
+## 0. First Prompt to Paste into an AI Agent
+
+Use this prompt first when you want to install or update MCAF in an existing repo:
+
+```text
+Install or update MCAF for this repository using these canonical pages:
+- https://mcaf.managed-code.com/tutorial
+- https://mcaf.managed-code.com/templates
+- https://mcaf.managed-code.com/skills
+
+Rules:
+- remove all legacy skills with prefix mcf-
+- install only current skills with prefix mcaf-
+- keep AGENTS.md in the repository root
+- if this is a multi-project solution, create or update local AGENTS.md files per project
+```
+
+---
+
 ## 1. Open the Canonical Pages
 
 Use these pages as the install surface:
 
-- Tutorial: [https://mcaf.managed-code.com/tutorial.html](https://mcaf.managed-code.com/tutorial.html)
-- Templates: [https://mcaf.managed-code.com/templates.html](https://mcaf.managed-code.com/templates.html)
-- Skills: [https://mcaf.managed-code.com/skills.html](https://mcaf.managed-code.com/skills.html)
+- Tutorial: [https://mcaf.managed-code.com/tutorial](https://mcaf.managed-code.com/tutorial)
+- Templates: [https://mcaf.managed-code.com/templates](https://mcaf.managed-code.com/templates)
+- Skills: [https://mcaf.managed-code.com/skills](https://mcaf.managed-code.com/skills)
 
 Use these raw template files for direct download:
 
@@ -66,7 +85,31 @@ Only create the directory for the agent runtime you actually use.
 
 Get the available skills from:
 
-- Skills page: [https://mcaf.managed-code.com/skills.html](https://mcaf.managed-code.com/skills.html)
+- Skills page: [https://mcaf.managed-code.com/skills](https://mcaf.managed-code.com/skills)
+
+### 4.0 Remove Legacy `mcf-*` Skills First
+
+Before installing current skills, delete old folders with prefix `mcf-` from your chosen target directory.
+
+Codex:
+
+```bash
+find .codex/skills -maxdepth 1 -mindepth 1 -type d -name 'mcf-*' -exec rm -rf {} +
+```
+
+Claude Code:
+
+```bash
+find .claude/skills -maxdepth 1 -mindepth 1 -type d -name 'mcf-*' -exec rm -rf {} +
+```
+
+Optional verification:
+
+```bash
+find .codex/skills .claude/skills -maxdepth 1 -mindepth 1 -type d -name 'mcf-*' 2>/dev/null
+```
+
+The result should be empty.
 
 For each selected skill:
 
@@ -112,21 +155,17 @@ The intended flow is:
 
 Add tool-specific .NET skills only when the repo standardizes on them:
 
-- `mcaf-dotnet-format`
-- `mcaf-dotnet-code-analysis`
-- `mcaf-dotnet-analyzer-config`
-- `mcaf-dotnet-complexity`
-- `mcaf-dotnet-stylecop-analyzers`
-- `mcaf-dotnet-roslynator`
-- `mcaf-dotnet-meziantou-analyzer`
-- `mcaf-dotnet-coverlet`
-- `mcaf-dotnet-reportgenerator`
-- `mcaf-dotnet-stryker`
-- `mcaf-dotnet-netarchtest`
-- `mcaf-dotnet-archunitnet`
-- `mcaf-dotnet-codeql`
-- `mcaf-dotnet-semgrep`
-- `mcaf-dotnet-csharpier`
+<!-- MCAF:DOTNET-OPTIONAL-SKILLS-BEGIN -->
+- Generated during site build from current `mcaf-dotnet-*` folders in `skills/`.
+<!-- MCAF:DOTNET-OPTIONAL-SKILLS-END -->
+
+### 4.2 Current Skill Catalog (Generated)
+
+The website build generates this list from the actual folders under `skills/`.
+
+<!-- MCAF:ALL-SKILLS-BEGIN -->
+- Generated during site build from `skills/*/SKILL.md`
+<!-- MCAF:ALL-SKILLS-END -->
 
 ---
 
@@ -202,6 +241,7 @@ The bootstrap is complete when:
 
 - root `AGENTS.md` exists
 - the right skill folders exist in the chosen skills directory
+- no legacy `mcf-*` skill folders remain in the chosen skills directory
 - local `AGENTS.md` files exist for project roots in a multi-project solution
 - docs and commands are customized to the real repo
 

docs/templates/AGENTS.md

@@ -104,6 +104,14 @@ If the stack is `.NET`, this usually includes:
 - `mcaf-architecture-overview` if the repo keeps a maintained architecture map
 - `mcaf-ci-cd`
 
+If the stack is `.NET`, document skill-management rules explicitly:
+
+- `mcaf-dotnet` is the entry skill and routes to specialized `.NET` skills.
+- Keep exactly one framework skill: `mcaf-dotnet-xunit` or `mcaf-dotnet-tunit` or `mcaf-dotnet-mstest`.
+- Add tool-specific `.NET` skills only when the repository actually uses those tools in CI or local verification.
+- Legacy `mcf-*` skills are forbidden. Remove old `mcf-*` folders and keep only `mcaf-*` skills in agent skill directories.
+- When upgrading skills, recheck `build`, `test`, `format`, `analyze`, and `coverage` commands against the repo toolchain.
+
 ## Rules to Follow (Mandatory)
 
 ### Commands

skills/mcaf-dotnet-analyzer-config/SKILL.md

@@ -47,6 +47,22 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT
 - IDE-only settings do not silently override repo policy
 - the default path is a root `.editorconfig`, not a surprise alternative
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/analyzer-config.md` first

skills/mcaf-dotnet-archunitnet/SKILL.md

@@ -36,6 +36,22 @@ compatibility: "Requires a .NET test project; supports dedicated integrations fo
 - architecture load cost is reasonable for the suite
 - rules are stable and tied to real boundaries
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/archunitnet.md` first

skills/mcaf-dotnet-code-analysis/SKILL.md

@@ -45,6 +45,22 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT
 - analyzer behavior is driven by repo config, not IDE defaults
 - CI can reproduce the same warnings and errors locally
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/code-analysis.md` first

skills/mcaf-dotnet-codeql/SKILL.md

@@ -36,6 +36,22 @@ compatibility: "Requires a GitHub-based or CLI-based CodeQL workflow; respects t
 - the chosen CodeQL path is allowed for the repo type
 - build mode is documented and reproducible
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/codeql.md` first

skills/mcaf-dotnet-complexity/SKILL.md

@@ -47,6 +47,22 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT
 - thresholds are versioned in repo, not held in IDE memory
 - complexity findings map to real refactoring decisions
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/complexity.md` first

skills/mcaf-dotnet-coverlet/SKILL.md

@@ -43,6 +43,22 @@ compatibility: "Requires a .NET test project or solution; respects the repo's `A
 - coverage driver matches the runner model
 - coverage files are stable and consumable by downstream reporting
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/coverlet.md` first

skills/mcaf-dotnet-csharpier/SKILL.md

@@ -38,6 +38,22 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT
 - formatter ownership is not ambiguous
 - the repo is comfortable with opinionated formatting decisions
 
+## Findings Loop
+
+When this skill is used to run a checker, analyzer, test gate, or verification command:
+
+1. Run the command in read-only or report mode first and collect findings.
+2. Return a concise findings list with only actionable items:
+   - rule or check id
+   - `file:line`
+   - one-line fix intent
+3. Fix findings in small batches without hiding rules unless the repo already documents an exception.
+4. Re-run the same command after each fix batch.
+5. Repeat until the gate passes or only explicitly accepted exceptions remain.
+6. Keep output trimmed: include counts and the top remaining items only, not raw full logs.
+
+For setup-only requests that do not execute checks, return `status: configured` and the exact commands that should be run later.
+
 ## Load References
 
 - read `references/csharpier.md` first