skils

Author: KSemenenko

README.md

@@ -45,7 +45,9 @@ In MCAF, repository context includes:
 - application code  
 - automated tests (unit, integration, API, UI/E2E)  
 - documentation for features, architecture, testing, development, and operations  
-- `skills/` packages (workflows + scripts + references) for repeatable agent tasks  
+- Agent Skills packages (workflows + scripts + references) for repeatable agent tasks  
+  - Codex: `.codex/skills/`  
+  - Claude Code: `.claude/skills/`  
 - the repository’s root `AGENTS.md`  
 
 Anything that matters for development, testing, or operations lives in the repository.
@@ -134,7 +136,8 @@ A skill is a folder that contains:
 
 Recommended layout:
 
-- `skills/<skill-name>/SKILL.md`
+- Codex: `.codex/skills/<skill-name>/SKILL.md`
+- Claude Code: `.claude/skills/<skill-name>/SKILL.md`
 
 Integration principle:
 
@@ -615,7 +618,9 @@ Used for:
 To adopt MCAF in a repository:
 
 1. A `docs/` directory exists with at least `Architecture/`, `Features/`, `ADR/`, `Testing`, and `Development` (and a `docs/Architecture/Overview.md` entry point).  
-2. A `skills/` directory exists with skills used by your agents (each skill has `SKILL.md`).  
+2. A skills directory exists in your agent’s supported location (each skill has `SKILL.md`):
+   - Codex: `.codex/skills/`
+   - Claude Code: `.claude/skills/`
 3. This Guide and a root `AGENTS.md` live at the repository root and are kept current.  
 4. Commands for `build`, `test`, `format`, and `analyze` are defined and documented.  
 5. Containerized or scripted environments exist for integration/API/UI tests.  
@@ -649,4 +654,4 @@ Every significant feature, document, and decision has an accountable owner:
 
 - **Onboarding**: New team members read this Guide, the root `AGENTS.md`, and key docs before making changes.
 - **Regular review**: The team periodically reviews `AGENTS.md` and docs to ensure they reflect current practices.
-- **Feedback loops**: Issues with AI agent behaviour are tracked and lead to updates in `AGENTS.md`, skills (`skills/*/SKILL.md`), and docs — not repeated chat corrections.
+- **Feedback loops**: Issues with AI agent behaviour are tracked and lead to updates in `AGENTS.md`, skills (`*/SKILL.md` in your skills directory), and docs — not repeated chat corrections.

TUTORIAL.md

@@ -8,7 +8,7 @@ Get MCAF running in your repository:
 
 1. Bootstrap AGENTS.md with AI analysis
 2. Create documentation structure in `docs/` (including `docs/Architecture/Overview.md`)
-3. Add skills in `skills/`
+3. Add skills (agent-specific directory)
 4. Document existing features
 5. Create ADRs for existing decisions
 6. Write feature docs before coding (ongoing workflow)
@@ -90,7 +90,15 @@ Report what you created.
 
 Skills are part of MCAF: keep them in-repo so agents and humans share the same workflows, scripts, and standards.
 
-Install baseline templates + skills:
+Where to put skills depends on your agent:
+
+- **Codex (OpenAI)**: `.codex/skills/`
+- **Claude Code (Anthropic)**: `.claude/skills/`
+- **Gemini Code Assist (Google)**: no documented Agent Skills folders (`SKILL.md`) like Codex/Claude; use `AGENTS.md` + docs, and control context with `.aiexclude`/`.gitignore` (Gemini CLI: `.geminiignore`)
+
+Baseline skills in this MCAF repo live under `skills/` (templates). The installer copies them into your chosen skills directory.
+
+Install baseline templates + skills (defaults to Codex: `.codex/skills/`):
 
 ```bash
 git clone https://github.com/managedcode/MCAF.git ../MCAF
@@ -99,13 +107,21 @@ git clone https://github.com/managedcode/MCAF.git ../MCAF
 bash ../MCAF/scripts/mcaf-install.sh
 ```
 
+Install skills for Claude Code instead:
+
+```bash
+bash ../MCAF/scripts/mcaf-install.sh --skills-dir .claude/skills
+```
+
 **Prompt:**
 
 ```
 Add skills structure to this project:
 
-1. Create `skills/` at repo root.
-2. Add baseline MCAF skills (copy `skills/` from the MCAF repo and then adapt to your repo):
+1. Create the agent skills directory at repo root:
+   - Codex: `.codex/skills/`
+   - Claude Code: `.claude/skills/`
+2. Add baseline MCAF skills (copy from the MCAF repo and then adapt to your repo):
    - `mcaf-architecture-overview`
    - `mcaf-feature-spec`
    - `mcaf-adr-writing`
@@ -119,9 +135,9 @@ Add skills structure to this project:
 4. Generate an “available skills” block for your agent runtime:
    - include only metadata (name, description, location)
    - prefer a simple XML `<available_skills>` block (easy to copy/paste and parse)
-   - generate from your repo (recommended): `python3 skills/mcaf-skill-curation/scripts/generate_available_skills.py skills --absolute`
+   - generate from your repo (example for Codex): `python3 .codex/skills/mcaf-skill-curation/scripts/generate_available_skills.py .codex/skills --absolute`
 5. Validate skills and fix reported issues:
-   - `python3 skills/mcaf-skill-curation/scripts/validate_skills.py skills`
+   - (example for Codex) `python3 .codex/skills/mcaf-skill-curation/scripts/validate_skills.py .codex/skills`
 
 Report what you created.
 ```
@@ -137,20 +153,28 @@ If your project already uses MCAF and you want to see what changed upstream (wit
 bash ../MCAF/scripts/mcaf-upstream-snapshot.sh
 ```
 
+For Claude Code repos (skills in `.claude/skills/`):
+
+```bash
+bash ../MCAF/scripts/mcaf-upstream-snapshot.sh --skills-dir .claude/skills
+```
+
 Then review and merge what you want (example):
 
 ```bash
 diff -ruN docs/templates .mcaf/upstream/<timestamp>/docs/templates | less
-diff -ruN skills .mcaf/upstream/<timestamp>/skills | less
+diff -ruN .codex/skills .mcaf/upstream/<timestamp>/.codex/skills | less
 ```
 
 After merging, validate skills and regenerate the metadata block:
 
 ```bash
-python3 skills/mcaf-skill-curation/scripts/validate_skills.py skills
-python3 skills/mcaf-skill-curation/scripts/generate_available_skills.py skills --absolute
+python3 .codex/skills/mcaf-skill-curation/scripts/validate_skills.py .codex/skills
+python3 .codex/skills/mcaf-skill-curation/scripts/generate_available_skills.py .codex/skills --absolute
 ```
 
+If you use a different skills directory, replace `.codex/skills` with your chosen path (for example `.claude/skills`).
+
 ---
 
 ## Step 4: Document Existing Features

docs/templates/AGENTS.md

@@ -108,10 +108,9 @@ If no new rule is detected → do not update the file.
 
 - All docs live in `docs/` (or `.wiki/`)
 - Global architecture entry point: `docs/Architecture/Overview.md` (read first)
-- When creating docs from `docs/templates/*`:
-  - copy the template, then remove every `TEMPLATE ONLY` note
-  - replace all placeholder text (`TODO:`, `...`, “FeatureName”, “ADR-XXXX”, etc.)
-  - real docs must not contain template instructions or placeholder scaffolding
+- When creating docs from templates:
+  - copy the template into its real docs location
+  - replace all placeholders and remove all template notes (real docs must be clean: no `TEMPLATE ONLY`, `TODO:`, `...`)
 - Update feature docs when behaviour changes
 - Update ADRs when architecture changes
 - Diagrams are mandatory in docs:

scripts/mcaf-install.sh

@@ -6,11 +6,12 @@ usage() {
 Install MCAF baseline templates + skills into the CURRENT directory (target repo root).
 
 Usage:
-  mcaf-install.sh [--force] [--repo <git-url>] [--ref <ref>]
+  mcaf-install.sh [--force] [--repo <git-url>] [--ref <ref>] [--skills-dir <path>]
 
 Defaults:
   --repo https://github.com/managedcode/MCAF.git
   --ref  main
+  --skills-dir .codex/skills
 
 Behaviour:
   - Without --force: do NOT overwrite existing files.
@@ -19,14 +20,15 @@ Behaviour:
 Output:
   - docs/templates/*
   - docs/Architecture/Overview.md (from template if missing)
-  - skills/* (baseline skills)
+  - <skills-dir>/* (baseline skills)
   - AGENTS.md (from template if missing)
 EOF
 }
 
 FORCE=0
 MCAF_REPO="https://github.com/managedcode/MCAF.git"
 MCAF_REF="main"
+SKILLS_DIR=".codex/skills"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -42,6 +44,10 @@ while [[ $# -gt 0 ]]; do
       MCAF_REF="${2:-}"
       shift 2
       ;;
+    --skills-dir)
+      SKILLS_DIR="${2:-}"
+      shift 2
+      ;;
     -h|--help)
       usage
       exit 0
@@ -70,20 +76,18 @@ mkdir -p \
   docs/Architecture \
   docs/ADR \
   docs/Features \
-  docs/Testing \
-  docs/Development \
-  skills
+  "$SKILLS_DIR"
 
 if [[ $FORCE -eq 1 ]]; then
   echo "Copying templates (overwrite enabled) ..."
   cp -R "$tmp_dir/mcaf/docs/templates/." docs/templates/
   echo "Copying skills (overwrite enabled) ..."
-  cp -R "$tmp_dir/mcaf/skills/." skills/
+  cp -R "$tmp_dir/mcaf/skills/." "$SKILLS_DIR/"
 else
   echo "Copying templates (no overwrite) ..."
   cp -R -n "$tmp_dir/mcaf/docs/templates/." docs/templates/ || true
   echo "Copying skills (no overwrite) ..."
-  cp -R -n "$tmp_dir/mcaf/skills/." skills/ || true
+  cp -R -n "$tmp_dir/mcaf/skills/." "$SKILLS_DIR/" || true
 fi
 
 if [[ ! -f AGENTS.md || $FORCE -eq 1 ]]; then
@@ -105,4 +109,5 @@ echo "Done."
 echo "Next:"
 echo "  1) Customize AGENTS.md with REAL commands and rules."
 echo "  2) Fill docs/Architecture/Overview.md (modules/boundaries + ADR links)."
-echo "  3) Run build/test/format commands from AGENTS.md to verify."
+echo "  3) Restart your agent so it reloads skills from: $SKILLS_DIR"
+echo "  4) Run build/test/format commands from AGENTS.md to verify."

scripts/mcaf-upstream-snapshot.sh

@@ -6,22 +6,24 @@ usage() {
 Fetch the latest MCAF templates + skills into a snapshot folder (safe for updating existing repos).
 
 Usage:
-  mcaf-upstream-snapshot.sh [--repo <git-url>] [--ref <ref>] [--out <dir>]
+  mcaf-upstream-snapshot.sh [--repo <git-url>] [--ref <ref>] [--out <dir>] [--skills-dir <path>]
 
 Defaults:
   --repo https://github.com/managedcode/MCAF.git
   --ref  main
   --out  .mcaf/upstream/<timestamp>/
+  --skills-dir .codex/skills
 
 Notes:
   - Run this from the TARGET repo root.
-  - This does NOT overwrite your current docs/templates or skills.
+  - This does NOT overwrite your current docs/templates or skills dir.
 EOF
 }
 
 MCAF_REPO="https://github.com/managedcode/MCAF.git"
 MCAF_REF="main"
 OUT_DIR=""
+SKILLS_DIR=".codex/skills"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -37,6 +39,10 @@ while [[ $# -gt 0 ]]; do
       OUT_DIR="${2:-}"
       shift 2
       ;;
+    --skills-dir)
+      SKILLS_DIR="${2:-}"
+      shift 2
+      ;;
     -h|--help)
       usage
       exit 0
@@ -70,12 +76,13 @@ git -C "$tmp_dir/mcaf" rev-parse HEAD > "$OUT_DIR/mcaf.commit"
 
 mkdir -p "$OUT_DIR/docs"
 cp -R "$tmp_dir/mcaf/docs/templates" "$OUT_DIR/docs/"
-cp -R "$tmp_dir/mcaf/skills" "$OUT_DIR/"
+mkdir -p "$OUT_DIR/$SKILLS_DIR"
+cp -R "$tmp_dir/mcaf/skills/." "$OUT_DIR/$SKILLS_DIR/"
 
 echo ""
 echo "Upstream snapshot written to: $OUT_DIR"
 echo "Commit: $(cat "$OUT_DIR/mcaf.commit")"
 echo ""
 echo "Review diffs:"
 echo "  diff -ruN docs/templates \"$OUT_DIR/docs/templates\" | less"
-echo "  diff -ruN skills \"$OUT_DIR/skills\" | less"
+echo "  diff -ruN \"$SKILLS_DIR\" \"$OUT_DIR/$SKILLS_DIR\" | less"

skills/mcaf-adr-writing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mcaf-adr-writing
-description: Create or update an ADR under `docs/ADR/` using `docs/templates/ADR-Template.md`, capturing context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure the ADR is self-contained, has a Mermaid diagram, and defines testable invariants.
-compatibility: Requires repository write access; produces Markdown docs with Mermaid diagrams.
+description: "Create or update an ADR under `docs/ADR/` using `docs/templates/ADR-Template.md`, capturing context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure the ADR is self-contained, has a Mermaid diagram, and defines testable invariants."
+compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams."
 ---
 
 # MCAF: ADR Writing
@@ -29,7 +29,7 @@ Before writing, make the ADR executable (no placeholders, no hand-waving):
    - what module(s) are affected
    - follow `AGENTS.md` scoping rules: Architecture map → linked ADR/Feature → entry points (do not scan everything)
 2. Start from `docs/templates/ADR-Template.md`.
-   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real ADR.
+   - keep the ADR’s `## Implementation plan (step-by-step)` updated while executing
 3. Write the ADR as a decision record:
    - **Context**: constraints + why this is needed now
    - **Decision**: a short, direct statement

skills/mcaf-architecture-overview/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mcaf-architecture-overview
-description: Create or update `docs/Architecture/Overview.md` for a repository: map modules and boundaries, add a Mermaid module diagram, document dependency rules, and link to ADRs/features. Use when onboarding, refactoring, adding modules, or when the repo lacks a clear global architecture map.
-compatibility: Requires repository write access; produces Markdown docs with Mermaid diagrams.
+description: "Create or update `docs/Architecture/Overview.md` for a repository: map modules and boundaries, add a Mermaid module diagram, document dependency rules, and link to ADRs/features. Use when onboarding, refactoring, adding modules, or when the repo lacks a clear global architecture map."
+compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams."
 ---
 
 # MCAF: Architecture Overview
@@ -25,12 +25,12 @@ This doc is the **global map**: boundaries, modules, and dependency rules.
 ## Workflow
 
 1. Open `docs/Architecture/Overview.md` if it exists; otherwise start from `docs/templates/Architecture-Template.md`.
-   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real doc.
+   - Ensure it contains a short `## Scoping (read first)` section (this is how we prevent “scan everything” behaviour).
 2. Identify the **real** top-level boundaries:
    - entry points (HTTP/API, CLI, UI, jobs, events)
    - modules/layers (group by folders/namespaces, not individual files)
    - external dependencies (only those that actually exist)
-3. Fill the **TL;DR** so a new engineer can orient in ~1 minute.
+3. Fill the **Summary** so a new engineer can orient in ~1 minute.
 4. Draw the Mermaid diagram as a **module map**:
    - keep it small (roughly 8–15 nodes)
    - label arrows with meaning (calls, events, reads/writes)

skills/mcaf-feature-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mcaf-feature-spec
-description: Create or update a feature document under `docs/Features/` using `docs/templates/Feature-Template.md`, including business rules, user flows, system behaviour, Mermaid diagram, verification plan, and Definition of Done. Use before implementing a non-trivial feature or when behaviour changes; make the spec executable (test flows + traceability to tests).
-compatibility: Requires repository write access; produces Markdown docs with Mermaid diagrams and executable verification steps.
+description: "Create or update a feature document under `docs/Features/` using `docs/templates/Feature-Template.md`, including business rules, user flows, system behaviour, Mermaid diagram, verification plan, and Definition of Done. Use before implementing a non-trivial feature or when behaviour changes; make the spec executable (test flows + traceability to tests)."
+compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams and executable verification steps."
 ---
 
 # MCAF: Feature Spec
@@ -26,8 +26,8 @@ Write a spec that can be implemented and verified **without guessing**:
 
 1. Start from `docs/Architecture/Overview.md` to pick the affected module(s).
 2. Create/update the feature doc using `docs/templates/Feature-Template.md`.
-   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real spec.
    - follow `AGENTS.md` scoping rules (do not scan the whole repo; use the architecture map to stay focused)
+   - keep the feature’s `## Implementation plan (step-by-step)` updated while executing
 3. Define behaviour precisely:
    - purpose and scope (in/out)
    - business rules (numbered, testable)

skills/mcaf-formatting/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mcaf-formatting
-description: Format code and keep style consistent using the repository’s canonical formatting/lint commands from AGENTS.md. Use after implementing changes or when formatting drift causes noisy diffs; keep formatting changes intentional and verified with build/tests.
-compatibility: Requires the repository’s formatter/linter tools; uses commands from AGENTS.md.
+description: "Format code and keep style consistent using the repository’s canonical formatting/lint commands from AGENTS.md. Use after implementing changes or when formatting drift causes noisy diffs; keep formatting changes intentional and verified with build/tests."
+compatibility: "Requires the repository’s formatter/linter tools; uses commands from AGENTS.md."
 ---
 
 # MCAF: Formatting
@@ -18,10 +18,9 @@ compatibility: Requires the repository’s formatter/linter tools; uses commands
 3. Review the diff:
    - ensure changes are formatting-only
    - if the formatter touched many files, separate the change or confirm it was explicitly requested
-4. Verify after formatting (use `AGENTS.md` commands):
-   - run `test` (at least new/related suites)
-   - run `build` if required by `AGENTS.md`
-   - run `analyze` if required by `AGENTS.md`
+4. Verify (follow `AGENTS.md` for sequencing + required commands):
+   - for formatting-only changes: run the smallest meaningful verification the repo requires (build/tests/analyze as applicable)
+   - for formatting as part of a behaviour change: follow the repo’s normal order (don’t reorder the pipeline)
 5. If `format`/linters are missing or flaky:
    - fix `AGENTS.md` to point to a real, repeatable command
    - only then rerun formatting

skills/mcaf-memory/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: mcaf-memory
-description: Maintain a persistent project memory file (`skills/mcaf-memory/references/memory.md`) with stable facts, constraints, preferences, and glossary so agents don’t re-learn the same context every chat. Use when the user says “remember”, gives repeating feedback, or when important project constraints are discovered.
-compatibility: Requires repository write access; stores memory in Markdown.
+description: "Maintain a persistent project memory file (`references/memory.md` in this skill folder) with stable facts, constraints, preferences, and glossary so agents don’t re-learn the same context every chat. Use when the user says “remember”, gives repeating feedback, or when important project constraints are discovered."
+compatibility: "Requires repository write access; stores memory in Markdown."
 ---
 
 # MCAF: Memory
 
 ## Output
 
-- `skills/mcaf-memory/references/memory.md` (create/update)
+- `references/memory.md` (create/update)
 
 ## When to use (triggers)
 
@@ -19,7 +19,7 @@ compatibility: Requires repository write access; stores memory in Markdown.
 
 ## Workflow
 
-1. Open `skills/mcaf-memory/references/memory.md`.
+1. Open `references/memory.md`.
 2. Keep the “7 Questions (profile)” up to date:
    - fill the answers as short bullets
    - these answers must reflect the real workflow (TDD, docs, release discipline)
@@ -37,7 +37,7 @@ compatibility: Requires repository write access; stores memory in Markdown.
    - **Rules/commands for agents** → `AGENTS.md`
    - **Architecture decisions** → `docs/ADR/*`
    - **Behaviour/flows** → `docs/Features/*`
-   - **Long-lived context & preferences** → `skills/mcaf-memory/references/memory.md`
+   - **Long-lived context & preferences** → `references/memory.md`
 6. Never store secrets or personal data.
 
 ## Guardrails