docs(steering): add claude-skills steering file for .claude/skills/* paths

[rjmurillo-bot]

Pull Request

Summary

Create domain-specific steering guidance for .claude/skills/* paths. This prevents scope explosion, language violations, and missing validation during skill development, based on learnings from PR #908.

Specification References

Type	Reference	Description
Issue	Fixes #951	[Documentation] Create steering file for .claude/skills/* paths

Changes

• Add .agents/steering/claude-skills.md with pre-flight checks, language policy (ADR-042), scope control thresholds, naming conventions, and before-PR checklist
• Add .github/instructions/claude-skills.instructions.md as Copilot entry point
• Update .agents/steering/README.md directory listing and steering files table

Type of Change

• Documentation update

Testing

• No testing required (documentation only)
• markdownlint passes (0 errors)
• pytest passes (2228 passed, 1 pre-existing failure unrelated to changes)

Agent Review

Security Review

• No security-critical changes in this PR

Other Agent Reviews

• Self-review completed

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated (if applicable)
• No new warnings introduced

Related Issues

Fixes #951

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[github-actions]

PR Validation Report

Tip

✅ Status: PASS

Description Validation

Check	Status
Description matches diff	PASS

QA Validation

Check	Status
Code changes detected	False
QA report exists	N/A

---

_{Powered by PR Validation workflow}

[gemini-code-assist]

Code Review

This pull request introduces steering guidance for Claude skills by adding a new documentation file, .github/instructions/claude-skills.instructions.md. This file acts as a quick reference and an entry point for AI assistants like Copilot, directing them to the main steering document. The changes are well-contained and align with the stated goal. I have reviewed the new file and found no high or critical issues. The documentation is clear and follows standard Markdown practices.

[github-actions]

AI Quality Gate Review

Warning

⚠️ Final Verdict: WARN

Walkthrough

This PR was reviewed by six AI agents in parallel, analyzing different aspects of the changes:

• Security Agent: Scans for vulnerabilities, secrets exposure, and security anti-patterns
• QA Agent: Evaluates test coverage, error handling, and code quality
• Analyst Agent: Assesses code quality, impact analysis, and maintainability
• Architect Agent: Reviews design patterns, system boundaries, and architectural concerns
• DevOps Agent: Evaluates CI/CD, build pipelines, and infrastructure changes
• Roadmap Agent: Assesses strategic alignment, feature scope, and user value

Review Summary

Agent	Verdict	Category	Status
Security	PASS	N/A	✅
QA	PASS	N/A	✅
Analyst	WARN	N/A	⚠️
Architect	WARN	N/A	⚠️
DevOps	PASS	N/A	✅
Roadmap	PASS	N/A	✅

💡 Quick Access: Click on individual agent jobs (e.g., "🔒 security Review", "🧪 qa Review") in the workflow run to see detailed findings and step summaries.

Security Review Details

Security Review: PR #1279

PR Type Classification

Category	Files	Security Scrutiny
DOCS	.agents/steering/README.md	None required
DOCS	.agents/steering/claude-skills.md	None required
DOCS	.github/instructions/claude-skills.instructions.md	None required

All 3 changed files are documentation (markdown). No CODE, WORKFLOW, or CONFIG files modified.

Findings

Severity	Category	Finding	Location	CWE
-	-	No security issues	-	-

Analysis Summary

• No credentials or secrets: Files contain only steering guidelines and documentation
• No code execution: Markdown files with no executable content
• No sensitive data exposure: Internal development guidelines only
• No prompt injection surface: These are internal steering docs, not system prompts
• Example values are safe: File paths shown are illustrative patterns only

Verdict

VERDICT: PASS
MESSAGE: Documentation-only PR with no security-relevant changes. All 3 files are markdown steering documents containing development guidelines.

QA Review Details

VERDICT: [PASS]
MESSAGE: Documentation-only PR with valid markdown structure and no broken links.

PR TYPE: DOCS
FILES:
- .agents/steering/README.md (DOCS)
- .agents/steering/claude-skills.md (DOCS)
- .github/instructions/claude-skills.instructions.md (DOCS)

EVIDENCE:
- Tests found: N/A - DOCS only
- Test execution: PASS - pytest 4572 passed, 3 skipped (pre-existing, unrelated to changes)
- Edge cases: N/A - DOCS only
- Error handling: N/A - DOCS only
- Blocking issues: 0

QUALITY ASSESSMENT:

| Area | Status | Evidence |
|------|--------|----------|
| Markdown syntax | [PASS] | Valid YAML frontmatter, proper heading hierarchy |
| Internal links | [PASS] | Links to ADR-005, ADR-042, testing-approach.md use correct relative paths |
| Content consistency | [PASS] | Instructions file correctly references steering file |
| applyTo pattern | [PASS] | Updated from `.claude/skills/**/*` to `.claude/skills/**` (consistent across files) |

VERIFICATION:
- Steering file frontmatter is valid YAML with required fields (name, applyTo, priority, version, status)
- Instructions file frontmatter matches steering file pattern
- README table correctly updated to reflect new description and pattern
- No executable code in changed files
- PR scope is focused (3 files, all documentation)

Analyst Review Details

Based on my analysis of the PR diff and current file state, here is my review:

---

Code Quality Score

Criterion	Score (1-5)	Notes
Readability	5	Clear tables, consistent formatting, well-structured sections
Maintainability	5	Single source of truth architecture with Copilot entry points
Consistency	5	Follows established steering file format from README.md
Simplicity	4	Comprehensive but could consolidate anti-patterns tables

Overall: 4.75/5

Impact Assessment

• Scope: Isolated (documentation only, 3 files changed)
• Risk Level: Low
• Affected Components: .agents/steering/claude-skills.md, .github/instructions/claude-skills.instructions.md, .agents/steering/README.md

Findings

Priority	Category	Finding	Location
Low	Documentation	Broken relative link: [Steering README](.agents/steering/README.md) should be [Steering README](./README.md)	claude-skills.md:178
Low	Consistency	applyTo pattern changed from .claude/skills/**/* to .claude/skills/** - verify glob behavior is equivalent	claude-skills.md:3
Low	Documentation	excludeFrom changed from node_modules to *.Tests.ps1 - confirms test exclusion strategy	claude-skills.md:4

Recommendations

1. Fix the broken relative link in claude-skills.md line 178. Path .agents/steering/README.md is invalid from within .agents/steering/. Should be ./README.md.

2. The glob pattern change from .claude/skills/**/* to .claude/skills/** is correct for GitHub Copilot custom instructions. The ** pattern already matches all nested files and directories.

3. The excludeFrom change from node_modules to *.Tests.ps1 aligns with routing Pester tests to testing-approach.md steering instead. This is a valid architectural decision.

Verdict

VERDICT: WARN
MESSAGE: Minor broken link in References section. Content is well-structured and follows steering conventions. Link fix required before merge.

Architect Review Details

I now have sufficient context to provide the architectural review. This is a documentation-only PR that updates steering guidance for Claude skills development.

Design Quality Assessment

Aspect	Rating (1-5)	Notes
Pattern Adherence	5	Follows steering pattern established in .agents/steering/
Boundary Respect	5	Changes limited to documentation layer only
Coupling	5	Loose coupling; instructions file points to steering file
Cohesion	5	Single responsibility: skill development guidance
Extensibility	5	Modular structure allows future additions

Overall Design Score: 5/5

Architectural Concerns

Severity	Concern	Location	Recommendation
Low	Broken relative link	claude-skills.md:178	Fix [Steering README](.agents/steering/README.md) to [Steering README](./README.md)

The link .agents/steering/README.md will not resolve correctly from within .agents/steering/ directory. Should be ./README.md.

Breaking Change Assessment

• Breaking Changes: No
• Impact Scope: None
• Migration Required: No
• Migration Path: N/A

Technical Debt Analysis

• Debt Added: None
• Debt Reduced: Low (consolidates guidance, reduces confusion)
• Net Impact: Improved

ADR Assessment

• ADR Required: No
• Decisions Identified: None (references existing ADR-042 and ADR-005)
• Existing ADR: ADR-042 (Python migration), ADR-040 (frontmatter standards)
• Recommendation: N/A

Architecture Alignment Check

Verification	Status	Notes
ADR-042 alignment	[PASS]	Correctly references Python-first policy
ADR-040 alignment	[PASS]	Frontmatter requirements align with ADR-040
ADR-005 reference	[PASS]	Correctly notes supersession for new development
SKILL-AUTHORING.md consistency	[PASS]	No contradictions with existing guide

Recommendations

1. Fix the broken relative link on line 178 of claude-skills.md:
   • Current: [Steering README](.agents/steering/README.md)
   • Should be: [Steering README](./README.md)

VERDICT: WARN
MESSAGE: Documentation-only changes with sound structure. One broken relative link should be fixed before merge.

DevOps Review Details

DevOps Review: PR #1279

PR Scope Detection

Category: DOCS

Changed Files:

• .agents/steering/README.md - Documentation
• .agents/steering/claude-skills.md - Documentation
• .github/instructions/claude-skills.instructions.md - Copilot instructions (template)

Review Scope: None required (documentation-only PR)

---

Pipeline Impact Assessment

Area	Impact	Notes
Build	None	No build changes
Test	None	No test infrastructure changes
Deploy	None	No deployment changes
Cost	None	No CI/CD cost impact

---

CI/CD Quality Checks

Check	Status	Location
Workflow files modified	N/A	No workflow changes
Actions pinned	N/A	No actions used
Secrets secure	N/A	No secrets referenced
Permissions minimal	N/A	No permissions configured
Shell scripts robust	N/A	No scripts modified

---

Findings

Severity	Category	Finding	Location	Fix
Low	Documentation	Minor broken link in references	.agents/steering/claude-skills.md:179	Link .agents/steering/README.md missing leading ../../

The reference link on line 179 points to .agents/steering/README.md instead of ../../.agents/steering/README.md or just ./README.md. This is a minor issue since it is in the same directory.

---

Template Assessment

• PR Template: Adequate (follows project conventions)
• Issue Templates: Not affected
• Copilot Instructions: Updated appropriately with matching applyTo patterns

---

Automation Opportunities

None identified. This PR appropriately creates steering documentation for skill development.

---

Recommendations

1. Consider fixing the relative link on line 179 to ./README.md for consistency with other relative references in the file.

---

Verdict

VERDICT: PASS
MESSAGE: Documentation-only PR with no CI/CD impact. Content is well-structured and aligned with project conventions.

Roadmap Review Details

Roadmap Review: PR #1279

Strategic Alignment Assessment

Criterion	Rating	Notes
Aligns with project goals	High	Codifies learnings from PR #908, prevents future scope explosion
Priority appropriate	High	Documentation debt that directly improves agent workflow quality
User value clear	High	Developers get clear guardrails for skill creation
Investment justified	High	3 files changed, low effort for high-leverage governance

Feature Completeness

• Scope Assessment: Right-sized
• Ship Ready: Yes
• MVP Complete: Yes
• Enhancement Opportunities: None identified. The steering file is comprehensive.

Impact Analysis

Dimension	Assessment	Notes
User Value	High	Prevents scope creep and language violations in skill PRs
Business Impact	Medium	Reduces review cycles and rework; improves PR quality
Technical Leverage	High	Reusable governance pattern; enforced via Copilot instructions
Competitive Position	Neutral	Internal tooling improvement

Concerns

Priority	Concern	Recommendation
Low	Reference path typo in line 178	.agents/steering/README.md vs ../../.agents/steering/README.md - verify link works

Recommendations

1. Merge as-is. The steering file consolidates PR feat(skill): add reflect skill and auto-learning hook #908 learnings into actionable guidance.
2. Consider adding this steering file to onboarding documentation for new contributors.

Verdict

VERDICT: PASS
MESSAGE: Documentation directly addresses Issue #951, codifies proven constraints from PR #908 retrospective, and delivers clear developer guidance with minimal scope.

---

Run Details

Property	Value
Run ID	22483768409
Triggered by	pull_request on 1279/merge
Commit	60e288d065d1d785cb82f2e43fdfec78ba9d26f1

_{Powered by AI Quality Gate workflow}

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

Updates steering guidance for Claude skills development across three documentation files. Refines glob patterns in directory matching, restructures skills steering file with tables for language policies and naming conventions, and updates GitHub instructions to reflect new skill development standards.

Changes

Cohort / File(s)	Summary
Steering Documentation Index .agents/steering/README.md	Updated claude-skills.md description from "Skill development guidance" to "Skill development standards" and refined applyTo glob pattern from .claude/skills/**/* to .claude/skills/**.
Skills Steering Guidelines .agents/steering/claude-skills.md	Restructured guidance into tables (language policies, naming conventions, scope signals). Changed applyTo pattern to .claude/skills/** and excludeFrom to .claude/skills/**/*.Tests.ps1. Replaced narrative sections with concrete examples, checklist format, and explicit artifact structure. Added language policy table (Python-first for new scripts, PowerShell grandfathered) with testing requirements and scope control criteria.
GitHub Quick Reference .github/instructions/claude-skills.instructions.md	Updated glob pattern match and title to "Quick Reference - Skills". Replaced required files guidance with directory structure diagram. Reworded scope control section as "Key Principles" with updated items: file count limit (10 or fewer), memory changes in separate PRs, SKILL.md frontmatter requirements, Python for new scripts (ADR-042), Pester tests required.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• rjmurillo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows conventional commit format with 'docs(steering):' prefix and clearly describes the main change of adding steering guidance for .claude/skills/* paths.
Description check	✅ Passed	Description is directly related to the changeset, explaining the purpose, files affected, and testing results for the steering file additions.
Linked Issues check	✅ Passed	All coding requirements from issue #951 are met: steering file created with pre-flight checks, language policy, scope control, naming conventions, before-PR checklist, and Copilot instructions added.
Out of Scope Changes check	✅ Passed	All changes are scoped to the steering documentation objectives: claude-skills.md, instructions file, and README updates match the requirements in issue #951.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/220-autonomous

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[rjmurillo]

Review Triage Required

Note

Priority: NORMAL - Human approval required before bot responds

Review Summary

Source	Reviews	Comments
Human	1	0
Bot	1	0

Next Steps

1. Review human feedback above
2. Address any CHANGES_REQUESTED from human reviewers
3. Add triage:approved label when ready for bot to respond to review comments

---

_{Powered by PR Maintenance workflow - Add triage:approved label}