Skip to content

Commit c0bbc6e

Browse files
KSemenenkoKSemenenko
committed
Expand skill library and reorganize templates
1 parent f6d2adc commit c0bbc6e

File tree

80 files changed

+2883
-746
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+2883
-746
lines changed

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

Lines changed: 167 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -29,27 +29,61 @@ jobs:
2929
- name: Check for content changes
3030
id: changes
3131
run: |
32-
git fetch origin main --depth=2
33-
# Only these files trigger a release (docs + templates + skills + scripts)
34-
CONTENT_CHANGES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -E '^(README\.md|TUTORIAL\.md|CREDITS\.md|docs/|skills/|scripts/)' || true)
35-
# Release only if there are documentation changes
32+
if [ "${{ github.event_name }}" = "push" ] && [ -n "${{ github.event.before }}" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
33+
CONTENT_CHANGES=$(git diff --name-only "${{ github.event.before }}" "${{ github.sha }}" 2>/dev/null | grep -E '^(README\.md|TUTORIAL\.md|CREDITS\.md|docs/|skills/|\.github/workflows/jekyll-gh-pages\.yml)' || true)
34+
else
35+
CONTENT_CHANGES=$(git ls-files README.md TUTORIAL.md CREDITS.md docs skills .github/workflows/jekyll-gh-pages.yml 2>/dev/null || true)
36+
fi
3637
if [ -n "$CONTENT_CHANGES" ]; then
37-
echo "Documentation changes detected:"
38+
echo "Documentation or packaging changes detected:"
3839
echo "$CONTENT_CHANGES"
3940
echo "release=true" >> $GITHUB_OUTPUT
4041
else
4142
echo "No documentation changes, skipping release"
4243
echo "release=false" >> $GITHUB_OUTPUT
4344
fi
4445
46+
- name: Validate skill reference links
47+
run: |
48+
python3 - <<'PY'
49+
from pathlib import Path
50+
import re
51+
52+
repo = Path(".").resolve()
53+
link_re = re.compile(r"\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)")
54+
ignore = {"overview-template.md"}
55+
56+
failures = []
57+
for path in sorted((repo / "skills").glob("*/references/*.md")):
58+
if path.name.endswith("-template.md") or path.name in ignore:
59+
continue
60+
text = path.read_text(encoding="utf-8")
61+
for target in link_re.findall(text):
62+
if target.startswith(("http://", "https://", "mailto:", "/", "#")):
63+
continue
64+
resolved = (path.parent / target).resolve()
65+
try:
66+
rel = resolved.relative_to(repo)
67+
except ValueError:
68+
continue
69+
if not (repo / rel).exists():
70+
failures.append(f"{path.relative_to(repo)} -> {target}")
71+
72+
if failures:
73+
print("Broken local reference links found:")
74+
for failure in failures:
75+
print(f" - {failure}")
76+
raise SystemExit(1)
77+
78+
print("Skill reference links OK")
79+
PY
80+
4581
- name: Set version
4682
id: version
4783
run: |
48-
# Version scheme: use MAJOR.MINOR from the repo `VERSION` file, and auto-increment PATCH via GitHub run number.
49-
# Example: if `VERSION` contains `1.1.0`, the workflow produces `1.1.<run_number>`.
5084
BASE_VERSION="$(tr -d '\r\n' < VERSION 2>/dev/null || true)"
5185
if [[ ! "$BASE_VERSION" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
52-
echo "ERROR: VERSION must be in SemVer format: MAJOR.MINOR.PATCH (example: 1.1.0). Got: '$BASE_VERSION'" >&2
86+
echo "ERROR: VERSION must be in SemVer format: MAJOR.MINOR.PATCH (example: 1.2.0). Got: '$BASE_VERSION'" >&2
5387
exit 2
5488
fi
5589
MAJOR="${BASH_REMATCH[1]}"
@@ -72,86 +106,133 @@ jobs:
72106
echo "version: \"${{ steps.version.outputs.VERSION }}\"" >> github-pages/_config.yml
73107
echo "build_date: \"$(date +'%Y-%m-%d')\"" >> github-pages/_config.yml
74108
75-
- name: Generate templates page
109+
- name: Generate catalog pages
76110
run: |
77-
cat > github-pages/templates.md << 'HEADER'
78-
---
79-
layout: default
80-
title: Templates
81-
description: Download ready-to-use templates for MCAF and vibe coding. Includes AGENTS.md template for Claude Code, Codex, Gemini, Cursor, ADR templates, and feature documentation for AI-assisted development.
82-
keywords: MCAF templates, AGENTS.md template, vibe coding templates, AI-assisted development, ADR template, Claude Code, Codex, Gemini, Cursor rules
83-
nav_order: 2
84-
---
85-
86-
# Templates
87-
88-
Ready-to-use templates for adopting MCAF in your repository. <br/>
89-
These files define how AI agents work in your codebase, document architectural decisions, and describe features with clear test flows.
90-
91-
<div class="templates-list">
92-
HEADER
93-
sed -i 's/^ //' github-pages/templates.md
94-
95-
for file in docs/templates/*.md; do
96-
if [ -f "$file" ]; then
97-
filename=$(basename "$file")
98-
name="${filename%.md}"
99-
100-
echo "<div class=\"template-item\">" >> github-pages/templates.md
101-
echo "<span class=\"template-name\">${name}</span>" >> github-pages/templates.md
102-
echo "<div class=\"template-links\">" >> github-pages/templates.md
103-
echo "<a href=\"https://github.com/managedcode/MCAF/blob/main/docs/templates/${filename}\">View</a>" >> github-pages/templates.md
104-
echo "<a href=\"https://raw.githubusercontent.com/managedcode/MCAF/main/docs/templates/${filename}\" download>Download</a>" >> github-pages/templates.md
105-
echo "</div>" >> github-pages/templates.md
106-
echo "</div>" >> github-pages/templates.md
107-
fi
108-
done
109-
110-
echo "</div>" >> github-pages/templates.md
111-
112-
- name: Generate skills page
113-
run: |
114-
cat > github-pages/skills.md << 'HEADER'
115-
---
116-
layout: default
117-
title: Skills
118-
description: Download baseline MCAF Agent Skills (SKILL.md) for repeatable agent workflows: architecture overview, feature specs, ADRs, testing (TDD), formatting, and skill curation.
119-
keywords: MCAF skills, Agent Skills, SKILL.md, Claude Code skills, Codex skills, AI agent workflows, TDD, ADR, feature specs
120-
nav_order: 5
121-
---
122-
123-
# Skills
124-
125-
Baseline MCAF skills in Agent Skills format. Each skill is a folder under `skills/` containing a required `SKILL.md`.
126-
127-
<div class="templates-list">
128-
HEADER
129-
sed -i 's/^ //' github-pages/skills.md
130-
131-
for file in skills/*/SKILL.md; do
132-
if [ -f "$file" ]; then
133-
skill_dir=$(basename "$(dirname "$file")")
134-
135-
echo "<div class=\"template-item\">" >> github-pages/skills.md
136-
echo "<span class=\"template-name\">${skill_dir}</span>" >> github-pages/skills.md
137-
echo "<div class=\"template-links\">" >> github-pages/skills.md
138-
echo "<a href=\"https://github.com/managedcode/MCAF/blob/main/skills/${skill_dir}/SKILL.md\">View</a>" >> github-pages/skills.md
139-
echo "<a href=\"https://raw.githubusercontent.com/managedcode/MCAF/main/skills/${skill_dir}/SKILL.md\" download>Download</a>" >> github-pages/skills.md
140-
echo "</div>" >> github-pages/skills.md
141-
echo "</div>" >> github-pages/skills.md
142-
fi
143-
done
144-
145-
echo "</div>" >> github-pages/skills.md
111+
SITE_URL="$(awk -F'\"' '/^url:/{print $2}' github-pages/_config.yml)"
112+
export SITE_URL
113+
python3 - <<'PY'
114+
from __future__ import annotations
115+
116+
import os
117+
from pathlib import Path
118+
119+
repo = Path(".")
120+
site_url = os.environ["SITE_URL"].rstrip("/")
121+
github_raw = "https://raw.githubusercontent.com/managedcode/MCAF/main"
122+
github_blob = "https://github.com/managedcode/MCAF/blob/main"
123+
124+
def parse_frontmatter(skill_md: Path) -> dict[str, str]:
125+
text = skill_md.read_text(encoding="utf-8")
126+
lines = text.splitlines()
127+
data: dict[str, str] = {}
128+
if not lines or lines[0].strip() != "---":
129+
return data
130+
for line in lines[1:]:
131+
if line.strip() == "---":
132+
break
133+
if ":" not in line:
134+
continue
135+
key, value = line.split(":", 1)
136+
data[key.strip()] = value.strip().strip("\"'")
137+
return data
138+
139+
skills: list[dict[str, str]] = []
140+
for skill_md in sorted((repo / "skills").glob("*/SKILL.md")):
141+
skill_dir = skill_md.parent
142+
skill_name = skill_dir.name
143+
metadata = parse_frontmatter(skill_md)
144+
skills.append(
145+
{
146+
"name": skill_name,
147+
"description": metadata.get("description", ""),
148+
"folder_url": f"{github_blob}/skills/{skill_name}",
149+
"skill_md_url": f"{github_raw}/skills/{skill_name}/SKILL.md",
150+
}
151+
)
152+
153+
templates_page = repo / "github-pages" / "templates.md"
154+
templates_page.write_text(
155+
"\n".join(
156+
[
157+
"---",
158+
"layout: default",
159+
"title: Templates",
160+
"description: Minimal MCAF bootstrap templates for repository setup. Download AGENTS.md and CLAUDE.md directly, then fetch skills from their GitHub folders.",
161+
"keywords: MCAF templates, AGENTS.md template, CLAUDE.md template, AI coding bootstrap, MCAF bootstrap",
162+
"nav_order: 2",
163+
"---",
164+
"",
165+
"# Templates",
166+
"",
167+
"Public bootstrap templates are intentionally minimal. Everything else is distributed through skills.",
168+
"",
169+
"<div class=\"templates-list\">",
170+
"<div class=\"template-item\">",
171+
"<span class=\"template-name\">AGENTS</span>",
172+
"<div class=\"template-links\">",
173+
f"<a href=\"{github_blob}/docs/templates/AGENTS.md\">View</a>",
174+
f"<a href=\"{github_raw}/docs/templates/AGENTS.md\">Download</a>",
175+
"</div>",
176+
"</div>",
177+
"<div class=\"template-item\">",
178+
"<span class=\"template-name\">CLAUDE</span>",
179+
"<div class=\"template-links\">",
180+
f"<a href=\"{github_blob}/docs/templates/CLAUDE.md\">View</a>",
181+
f"<a href=\"{github_raw}/docs/templates/CLAUDE.md\">Download</a>",
182+
"</div>",
183+
"</div>",
184+
"</div>",
185+
"",
186+
]
187+
)
188+
+ "\n",
189+
encoding="utf-8",
190+
)
191+
192+
skills_page_lines = [
193+
"---",
194+
"layout: default",
195+
"title: Skills",
196+
"description: Baseline MCAF skills for architecture, ADRs, feature specs, maintainability, testing, CI/CD, security, observability, UI/UX, ML/AI delivery, and governance.",
197+
"keywords: MCAF skills, Agent Skills, SKILL.md, Codex skills, Claude Code skills, AI engineering workflows",
198+
"nav_order: 5",
199+
"---",
200+
"",
201+
"# Skills",
202+
"",
203+
f"Use these skill folders with the [tutorial]({site_url}/tutorial.html).",
204+
"",
205+
"<div class=\"templates-list\">",
206+
]
207+
for skill in skills:
208+
skills_page_lines.extend(
209+
[
210+
"<div class=\"template-item\">",
211+
f"<span class=\"template-name\">{skill['name']}</span>",
212+
f"<p>{skill['description']}</p>",
213+
"<div class=\"template-links\">",
214+
f"<a href=\"{skill['folder_url']}\">Folder</a>",
215+
f"<a href=\"{skill['skill_md_url']}\">Raw SKILL</a>",
216+
f"<a href=\"{github_blob}/skills/{skill['name']}/SKILL.md\">View</a>",
217+
"</div>",
218+
"</div>",
219+
]
220+
)
221+
skills_page_lines.extend(["</div>", ""])
222+
(repo / "github-pages" / "skills.md").write_text(
223+
"\n".join(skills_page_lines) + "\n",
224+
encoding="utf-8",
225+
)
226+
PY
146227
147228
- name: Copy TUTORIAL to github-pages
148229
run: |
149230
cat > github-pages/tutorial.md << 'EOF'
150231
---
151232
layout: default
152233
title: Tutorial
153-
description: Step-by-step tutorial for implementing MCAF in your project. Learn to set up AGENTS.md, configure Coding AI agents like Claude Code, Codex, Gemini, Cursor, and enable safe vibe coding with automated verification.
154-
keywords: MCAF tutorial, vibe coding tutorial, AI-assisted development, AI-assisted coding, AGENTS.md setup, Claude Code, Codex, Gemini, Cursor, GitHub Copilot
234+
description: Step-by-step tutorial for bootstrapping an MCAF v1.2 repository through URLs, bootstrap templates, and direct GitHub skill folders.
235+
keywords: MCAF tutorial, AGENTS.md setup, skill-first install, AI coding bootstrap, Codex skills, Claude Code skills
155236
nav_order: 3
156237
---
157238
EOF
@@ -164,8 +245,8 @@ jobs:
164245
---
165246
layout: default
166247
title: Credits
167-
description: Credits and acknowledgments for MCAF framework contributors. Learn about the team and inspirations behind the Managed Code Coding AI Framework.
168-
keywords: MCAF credits, ManagedCode team, AI framework contributors, acknowledgments
248+
description: Credits and acknowledgments for the people and projects that shaped the Managed Code Coding AI Framework.
249+
keywords: MCAF credits, Managed Code, AI framework contributors, engineering playbook acknowledgments
169250
nav_order: 4
170251
---
171252
EOF
@@ -180,8 +261,8 @@ jobs:
180261
---
181262
layout: default
182263
title: Guide
183-
description: MCAF is a framework that solves the problem of unpredictable AI coding. Build real production software with Coding AI agents using structured context, automated tests as verification gates, and AGENTS.md instructions. Vibe coding that actually works.
184-
keywords: MCAF, Coding AI Framework, AGENTS.md, vibe coding, AI-assisted development, AI-assisted coding, real software, production code, Claude Code, Codex, Gemini, ChatGPT, Cursor, GitHub Copilot, Windsurf, Cline, Aider, ManagedCode
264+
description: MCAF is a skill-first framework for building real software with AI coding agents using AGENTS.md, repository-native skills, and automated verification.
265+
keywords: MCAF, Coding AI Framework, AGENTS.md, AI-assisted development, AI coding skills, real software, Codex, Claude Code
185266
is_home: true
186267
nav_order: 1
187268
---
@@ -220,6 +301,8 @@ jobs:
220301

221302
- name: Upload artifact
222303
uses: actions/upload-pages-artifact@v3
304+
with:
305+
path: ./_site
223306

224307
deploy:
225308
runs-on: ubuntu-latest

‎CREDITS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Credits
22

33
MCAF is an open framework built by developers who believe AI coding agents need structure, not just prompts.
4-
This page recognizes the people who made it happen.
4+
This page recognizes the people and projects that influenced it.
55

66
## Contributors
77

@@ -10,8 +10,10 @@ This page recognizes the people who made it happen.
1010
## Special Thanks
1111

1212
- **<a href="https://www.linkedin.com/in/roger-johansson-4a4bb61/" target="_blank">Roger Johansson</a>** — His post about self-learning code agents inspired the self-learning logic that became the core of MCAF
13+
- **<a href="https://www.linkedin.com/in/christopherdbradford/" target="_blank" rel="noopener">Christopher Bradford</a>** — His human-review prompt strategy for large AI-generated code drops inspired the new review-planning skill and the idea of prioritizing review by user flow and risk
1314
- **<a href="https://agentskills.io" target="_blank" rel="noopener">Agent Skills</a>** — We’re grateful for this open specification (originally developed by Anthropic) that made “skills” concrete: file-based packaging, progressive disclosure, and practical integration patterns
1415
- **<a href="https://agents.md" target="_blank" rel="noopener">AGENTS.md</a>** — Thank you for standardizing the idea of a repository-native instruction file; this is a critical foundation for how MCAF treats agent rules as versioned, reviewable code
16+
- **<a href="https://github.com/microsoft/code-with-engineering-playbook" target="_blank" rel="noopener">Microsoft code-with-engineering-playbook</a>** — Its GitHub playbook informed the engineering reference material now packaged into the MCAF baseline skills
1517

1618
---
1719

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.1.43
1+
1.2.0

‎docs/templates/CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
@./AGENTS.md
1+
@./AGENTS.md

0 commit comments

Comments
 (0)