docs: add guidance for developing experimental skills

[AlvinStanescu]

Summary

• Add a Developing Experimental Skills section to CONTRIBUTING.md covering how to develop long-running / experimental work in this public repo
• Recommend feature-branch flow off main (no develop branch; use private fork only when work must stay confidential)
• Establish public-repo discipline: no secrets, customer-readable commits, experimental status callout in the SKILL.md body (per .claude/rules/skill-structure.md)
• Add feat/experimental/<skill-name> row to the existing branch-naming table for consistency

Background: came out of a Slack discussion with @gozhang / @mariusbughiu / @sherifmaktabi about developing the Maestro BPMN coding-agent skill — confirms feature branches are the right pattern and gives new contributors a clear story for when to merge to main (only when the skill is usable end-to-end, since main is what users install).

Test plan

• CI: pre-commit hooks pass (only doc changes, no SKILL.md frontmatter touched)
• Render CONTRIBUTING.md on GitHub and verify the new section, table-of-contents anchor, and added branch-naming row look correct
• Confirm relative link to .claude/rules/skill-structure.md resolves on GitHub

🤖 Generated with Claude Code

[github-actions]

Claude finished @AlvinStanescu's task in 1m 24s —— View job

---

Review of PR #625

Summary

Adds a "Developing Experimental Skills" section to CONTRIBUTING.md — covers feature-branch workflow for long-running skills, public-repo discipline, branch naming conventions, and merge-readiness criteria. Docs-only change, no skill files or frontmatter touched.

Change-by-Change Review

1. CONTRIBUTING.md — TOC entry (line 10)

Severity: OK
New [Developing Experimental Skills](#developing-experimental-skills) anchor added in the correct position between "Modifying an Existing Skill" and "Hooks". Anchor resolves to the new H2 at line 206. Clean.

2. CONTRIBUTING.md — New "Developing Experimental Skills" section (lines 206–245)

Severity: OK
Well-structured section with clear subsections: rationale, branch naming table, numbered workflow, and public-repo discipline. Specific observations:

• Public-repo callout (line 210): Good use of blockquote to highlight visibility. Sets the right tone up front.
• Branch naming table (lines 220–223): Consistent format with the existing table at lines 368–374. Covers both new-skill and existing-skill-extension patterns.
• Workflow steps (lines 227–238): Prescriptive and numbered — follows the content-quality rules for agent-and-human readability. The rebase-vs-merge guidance in step 3 is a nice practical detail.
• Experimental callout example (lines 232–236): Correctly follows .claude/rules/skill-structure.md guidance that preview/experimental status goes in the SKILL.md body, not frontmatter.
• Relative link on line 230: [.claude/rules/skill-structure.md](.claude/rules/skill-structure.md) — confirmed the target file exists at repo root. Resolves correctly from CONTRIBUTING.md.
• Merge criteria in step 5 (line 238): Cross-references [Quality Checklist](#quality-checklist) — anchor resolves to line 323. Good that it explicitly states smoke + e2e test requirements.
• Public-repo discipline (lines 240–245): Covers secrets, commit message tone, incident response for leaked secrets, and internal-tool screenshots. Solid security guidance.

3. CONTRIBUTING.md — Branch naming table row (line 372)

Severity: OK
New feat/experimental/<skill-name> row added to the existing branch-naming table in the "Pull Request Process" section. Consistent with the table introduced in the new section — no conflict, no duplication (the earlier table is scoped to experimental work; this one is the consolidated reference).

What's Missing

Nothing identified. This is a focused docs-only PR that adds a well-scoped section. No new skill paths are introduced, so no CODEOWNERS or test changes are needed.

Area Ratings

Area	Status	Notes
Frontmatter	N/A	No SKILL.md files changed
E2E Tests	N/A	Docs-only change
Skill Body	N/A	No skill files changed
References & Assets	N/A	No reference files changed
Repo Hygiene	OK	No secrets, no cross-skill refs, scoped change, relative link resolves

Issues for Manual Review

• Verify the rendered markdown on GitHub looks correct (table alignment, blockquote styling, fenced code block in the numbered list at step 4). Nested code blocks inside ordered lists can sometimes render oddly depending on GitHub's markdown parser.

Conclusion

Clean documentation PR. The new section is well-structured, consistent with existing conventions, and addresses a real contributor need. The guidance correctly references existing rules (experimental status in SKILL.md body, not frontmatter) and cross-links to the Quality Checklist for merge criteria. No issues found — looks good to merge.