Add Claude Code skills for content development workflows by vojtapolasek · Pull Request #14529 · ComplianceAsCode/content

vojtapolasek · 2026-03-04T13:45:57Z

Description:

Add 10 Claude Code skill definitions under .claude/skills/ that automate common development tasks: build-product, create-rule, draft-pr, inspect-control, map-controls, map-requirement, onboard-control, run-tests, test-rule, and shared MCP fallback utilities.
Skills cover the full development lifecycle: building products, creating and testing rules, mapping control file requirements, onboarding new security policies, and drafting PR descriptions.
Each skill is invoked as a slash command (e.g., /build-product rhel9) and is defined by a SKILL.md file documenting its purpose, arguments, phases, and behavior.
Skills optionally use the content-mcp MCP server for structured operations but fall back to filesystem-based alternatives when the MCP server is unavailable.
Add developer documentation (docs/manual/developer/12_ai_skills.md) describing how to find and use the skills.

Rationale:

These skills encode project-specific best practices, conventions, and workflows into reusable, self-documenting automation. They reduce onboarding friction for new contributors and help experienced contributors avoid repetitive manual steps.
The skills are compatible with any LLM client supporting the .claude/skills/ convention (Claude Code, Opencode, etc.), making AI-assisted development accessible across tooling.

Review Hints:

Key files to review:
- .claude/skills/shared/mcp_fallbacks.md — shared fallback procedures referenced by multiple skills
- .claude/skills/create-rule/SKILL.md — largest skill (~585 lines), covers rule creation end-to-end
- docs/manual/developer/12_ai_skills.md — developer-facing documentation
The skills themselves are Markdown instruction files, not executable code. Review them for accuracy of project conventions, correct command examples, and completeness of workflows.
No build or test infrastructure is affected. No products need to be rebuilt to verify this PR.
Review all commits together — the first commit adds all skills and the second adds documentation.

Introduces 10 skill definitions covering building, testing, rule creation, control file management, and PR workflows. Includes shared MCP fallback utilities for graceful degradation when the content-mcp server is unavailable. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

comps · 2026-03-06T09:17:01Z

The yamllint error is bogus, it detected --- (YAML document start) on the first line and assumed the .md file is YAML.

You might want to limit yamllint to specific file extensions or patterns in its config (or via -d), I've done that in https://github.com/RHSecurityCompliance/atex/blob/4181202326fe118d588cba72ec515e4c2c030eb2/.github/workflows/style.yaml#L30-L58 .

jan-cerny · 2026-03-06T11:26:32Z

.claude/skills/build-product/SKILL.md

+If ninja is available:
+```bash
+cd build
+cmake -G Ninja ..


I'd prefer to use the build_product script for ninja builds as well.

jan-cerny · 2026-03-06T11:30:18Z

.claude/skills/create-rule/SKILL.md

+
+3. **Rationale**: Why this rule is important for security
+
+4. **Severity**: One of `low`, `medium`, `high`, `unknown`


severity could have a default value, so that the users won't need to answer it

jan-cerny · 2026-03-06T11:33:28Z

.claude/skills/create-rule/SKILL.md

+## Important Notes
+
+- **Do NOT make test files executable** - the test framework handles this
+- **Use proper Jinja2 syntax** for macros in description, rationale, etc.


I wonder if this can trip it on a wrong path. Our project uses a custom Jinja syntax ie. we use triple braces instead of the default double braces.

jan-cerny · 2026-03-06T12:34:35Z

.claude/skills/test-rule/SKILL.md

+
+# Test Rule
+
+Run Automatus tests for a ComplianceAsCode security rule.


Can this skill build and use thin data streams? That'd make the test faster.

jan-cerny · 2026-03-23T12:46:33Z

It seems that currently the general opinion is that MCP servers should be used to connect to external providers (eg. Jira, database, language servers, online documentation). Skills usually don't use MCP servers to interact with the repository itself.

I somehow feel that by having 2 variants how to accomplish some task

We make creating Skill files more difficult for people because they need to describe some steps in 2 variants.
Skill files might be less consumable for agents.
aren't following best practices for writing Skills

What do you think about this?

vojtapolasek · 2026-03-26T14:29:58Z

I proposed a change to yamllint so that it does not cover other files: #14601

… it from the current project state

… this case

vojtapolasek · 2026-03-26T15:41:00Z

It seems that currently the general opinion is that MCP servers should be used to connect to external providers (eg. Jira, database, language servers, online documentation). Skills usually don't use MCP servers to interact with the repository itself.

MCP servers are like tools you give to the LLM. It is true that LLM can often figure out things on its own, but you lose some degree of precision and predictability. It is true that MCP servers are used rather for reading APIs, but isn't the directory and file layout of our project together with well defined file structure actually API as well?
My motivation for usage of MCP server was to increase predictability of skill outputs.

I somehow feel that by having 2 variants how to accomplish some task
* We make creating Skill files more difficult for people because they need to describe some steps in 2 variants.

I don't think so, nobody forces them to use the MCP server.

* Skill files might be less consumable for agents.

I don't think so, MCP servers are here exactly for agents to use them.

* aren't following best practices for writing Skills

Could you please point me to practices you refer to? Honestly, I did not read much of such practices, I used a skill to build skills, precisely this

What do you think about this?

I think the current approach is fine. It does not impose usage of MCP server. But I believe if the server is available, it should be used because it is more predictable.

jan-cerny · 2026-03-27T15:39:39Z

@vojtapolasek excellent! thanks for explanation

vojtapolasek and others added 2 commits March 4, 2026 14:31

add brief documentation regarding skills

3c822bf

vojtapolasek added this to the 0.1.81 milestone Mar 4, 2026

vojtapolasek added the enhancement General enhancements to the project. label Mar 4, 2026

jan-cerny reviewed Mar 6, 2026

View reviewed changes

jan-cerny self-assigned this Mar 6, 2026

vojtapolasek added 5 commits March 26, 2026 15:55

update build-product skill to always utilize build_prodct script

06f43f1

skills: remove hardcoded lists of templates or products, rather infer…

343b954

… it from the current project state

create-rule skill: make the "medium" severity the default one

1bd50a7

create-rule skill: mention usage of triple braces in Jinja expressions

5b997a9

test-rule skill: use thin datastreams when building a data stream for…

fca1d69

… this case

comps mentioned this pull request Mar 27, 2026

yamllint: cover all changed files ending in yaml, yml or fmf #14601

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Claude Code skills for content development workflows#14529

Add Claude Code skills for content development workflows#14529
vojtapolasek wants to merge 7 commits intoComplianceAsCode:masterfrom
vojtapolasek:add_skills

vojtapolasek commented Mar 4, 2026

Uh oh!

comps commented Mar 6, 2026

Uh oh!

jan-cerny Mar 6, 2026

Uh oh!

jan-cerny Mar 6, 2026

Uh oh!

jan-cerny Mar 6, 2026

Uh oh!

jan-cerny Mar 6, 2026

Uh oh!

jan-cerny commented Mar 23, 2026

Uh oh!

vojtapolasek commented Mar 26, 2026

Uh oh!

vojtapolasek commented Mar 26, 2026

Uh oh!

jan-cerny commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		3. Rationale: Why this rule is important for security

		4. Severity: One of `low`, `medium`, `high`, `unknown`


		# Test Rule

		Run Automatus tests for a ComplianceAsCode security rule.

Conversation

vojtapolasek commented Mar 4, 2026

Description:

Rationale:

Review Hints:

Uh oh!

comps commented Mar 6, 2026

Uh oh!

jan-cerny Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

jan-cerny Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

jan-cerny Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

jan-cerny Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

jan-cerny commented Mar 23, 2026

Uh oh!

vojtapolasek commented Mar 26, 2026

Uh oh!

vojtapolasek commented Mar 26, 2026

Uh oh!

jan-cerny commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants