feat(skills): add secure-by-design knowledge skill

[obrocki]

Description

Add the Secure by Design knowledge skill synthesizing the UK Government Secure by Design Principles (10 principles) and the Australian ASD/ACSC Secure by Design Foundations (6 foundations) into 11 structured reference documents for security assessment agents.

The skill follows the established OWASP skill pattern with a SKILL.md entrypoint and references/ directory containing one document per synthesized principle area. Each reference document includes source mappings, principle checklists, controls and mitigations, anti-patterns, and OWASP cross-references.

Registered in the security and hve-core-all collections as experimental.

Related Issue(s)

Closes #523

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

The secure-by-design skill is not directly user-invocable. It is consumed by the Security Reviewer orchestrator and Skill Assessor agent during security reviews. The Skill Assessor reads the SKILL.md entrypoint, then loads the relevant references/ documents to assess codebase adherence to Secure by Design principles.

Execution Flow:

1. The Skill Assessor agent receives a request to evaluate the secure-by-design skill.
2. It reads SKILL.md to discover the 11 normative references.
3. For each relevant principle area, it reads the corresponding reference document (e.g., references/03-secure-product-development.md).
4. It evaluates the codebase against the principle checklist and anti-patterns.
5. It returns structured findings with PASS/PARTIAL/FAIL per principle.

Output Artifacts:

Assessment findings are returned as structured data to the Security Reviewer orchestrator for inclusion in the final vulnerability report under .copilot-tracking/security/.

Success Indicators:

• The Skill Assessor can read all 12 reference files without errors.
• Each reference document contains source mappings, checklists, controls, anti-patterns, and OWASP cross-references.
• Assessment findings reference specific SBD identifiers (SBD-01 through SBD-11).

Testing

• npm run lint:md — passed (0 errors)
• npm run spell-check — passed (0 issues)
• npm run validate:skills — passed (secure-by-design validated, 0 errors)
• npm run lint:frontmatter — passed
• Manual review confirmed all 12 reference files follow the consistent structure established by other OWASP skills.
• Manual testing not performed.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable) (N/A — knowledge skill with no executable code)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — brace-expansion lockfile update only)
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

Additional Notes

The skill references two external government security frameworks:

• UK Government Secure by Design Principles
• Australian ASD/ACSC Secure by Design Foundations

The package-lock.json change is an incidental brace-expansion version bump (1.1.12 → 1.1.13, 5.0.2 → 5.0.5) unrelated to the skill addition.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.71%. Comparing base (84ddd5d) to head (1183d13).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1223      +/-   ##
==========================================
- Coverage   87.72%   87.71%   -0.02%     
==========================================
  Files          61       61              
  Lines        9320     9320              
==========================================
- Hits         8176     8175       -1     
- Misses       1144     1145       +1     

Flag	Coverage Δ
pester	85.31% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[WilliamBerryiii]

Converted to a draft until the PR checklist has been filled out and a PR description has been filled in.

[obrocki]

Converted to a draft until the PR checklist has been filled out and a PR description has been filled in.

Removed all "master" language - 00-principle-index.md title renamed to "Index of Secure by Design Principles" and references updated in SKILL.md skill layout section. Fixed typo "unrevoled" → "unrevoked" in 11-secure-deprecation.md. PR description and checklist filled in. Ready for re-review.

[katriendg]

How are we expecting the usage scenarios of this new skill? The title is very short and unsure how any platform agent will know how to / when to load the skill.
We should also probably document this is container the UK and Australian government guidance, potentially even in the title or some documentation?

I'm trying to imagine the right usage scenario for this skill. Is it intended only by the security-review agent, which has enough context to load the skill based on a specific request? I believe we may need to ensure additional documentation for this to be efficiently used by the right agent.

My recommendation is to give it a few iterations on your own code base and see if you get it to behave as expected. Or do we need a new prompt that picks up the security review agent then the skill by the right progressive disclosure built into the platform? Could you show an example of a efficient working prompt as well in the PR?

At this stage I have not yet reviewed the actual skill's referenced content, I'm more looking at it from a user scenario and expectations on how it can assist them. So really to get our discussion going at higher level.

[obrocki]

How are we expecting the usage scenarios of this new skill? The title is very short and unsure how any platform agent will know how to / when to load the skill. We should also probably document this is container the UK and Australian government guidance, potentially even in the title or some documentation?

I'm trying to imagine the right usage scenario for this skill. Is it intended only by the security-review agent, which has enough context to load the skill based on a specific request? I believe we may need to ensure additional documentation for this to be efficiently used by the right agent.

My recommendation is to give it a few iterations on your own code base and see if you get it to behave as expected. Or do we need a new prompt that picks up the security review agent then the skill by the right progressive disclosure built into the platform? Could you show an example of a efficient working prompt as well in the PR?

At this stage I have not yet reviewed the actual skill's referenced content, I'm more looking at it from a user scenario and expectations on how it can assist them. So really to get our discussion going at higher level.

Good question — I see your point!

I completely appreciate Secure by Design can be optional — as much as it's great to have it run by default (no pun intended), some may choose not to include it if it isn't relevant to them. Struggling to see why it wouldn't be, but the targetSkill fast-path keeps it opt-in while the Codebase Profiler's Technology Signals will recommend it automatically when governance and infrastructure artifacts are present.

The skill sources UK Government Secure by Design Principles (10 principles) and Australian ASD/ACSC Secure by Design Foundations (6 foundations) — documented in SKILL.md frontmatter and the principle index.

[katriendg]

Thank you for this contribution — the skill content looks well-structured and consistent with the OWASP skill pattern.

Left a few comments.
One of the main things in my earlier reflection was seeing how this skill would be used. I believe it needs to be included in the security reviewer, but no changes have been made there.

Also one item that's currently blocking CI: the Docusaurus test suite cross-validates the hardcoded artifact counts in docs/docusaurus/src/data/collectionCards.ts against the live collection YAML files. Adding secure-by-design to both security.collection.yml and hve-core-all.collection.yml shifted those counts, but collectionCards.ts wasn't updated to match.

This wasn't obvious from the existing docs — we're tracking a follow-up to add npm run docs:test to the PR checklist and contributing guide so future contributors don't hit the same thing.

For this PR, two values need updating:

// line 69 — security collection: 47 → 48
artifacts: 48,

// line 80 — hve-core-all meta count: 222 → 223
'hve-core-all': 223,

After editing, run npm run docs:test to confirm the tests pass before pushing to the PR branch.

Once you feel the PR is ready for re-review simply resolve all conversations, or leave open if you are unsure, and request a review again. Thanks!

[katriendg]

Thank you @obrocki for your many changes! I believe this looks good.

I notice you added a new prompt for the sbd, but also update the existing security review to include the reference to the skill. If you feel this works better we can keep it, but interested to understand.

We have one generic gap with the security review agent & skills which is more thorough documentation. Let's make sure there is a backlog item for this.

[WilliamBerryiii]

Licensing Compliance — Alignment with PR #1294

PR #1294 (chore/update-security-instruction-attributions) is standardizing licensing and attribution across all skills that derive content from third-party sources. This PR introduces content from two government sources that require proper attribution under their respective open licenses:

• UK Government — Crown Copyright, OGL-UK-3.0
• Australian Government — © Commonwealth of Australia, CC-BY-4.0

Changes needed

1. SKILL.md license field — Change MIT → OGL-UK-3.0 AND CC-BY-4.0
2. SKILL.md metadata — Resolve content_based_on type conflict (array here vs string in PR #1294 schema); add spec_version, framework_revision, last_updated, skill_based_on fields once PR #1294 lands
3. SKILL.md attribution section — Add ## Third-Party Attribution with dual-source attribution blocks
4. Reference files — Add attribution footers to all 12 reference files (00-principle-index.md through 11-secure-deprecation.md)
5. THIRD-PARTY-NOTICES — Add entries for both UK (OGL-UK-3.0) and Australian (CC-BY-4.0) sources

See inline comments for detailed templates and formatting guidance aligned with PR #1294's pattern.

If you'd rather defer this ... I can create a follow-up issue and get to it in 1294 so no stress. Just respond to @katriendg's comment and I'm happy to resolve this later.

[WilliamBerryiii]

Missing a ## Third-Party Attribution section before the footer. PR #1294 establishes a standard attribution block for all skills derived from third-party content. This skill requires dual attribution:

## Third-Party Attribution

### UK Government Secure by Design Principles

* **Copyright**: Crown Copyright, UK Government Security Group
* **License**: [Open Government Licence v3.0 (OGL-UK-3.0)](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
* **Source**: https://www.security.gov.uk/policy-and-guidance/secure-by-design/principles/
* **Modifications**: Synthesized into structured principle-checklist format with cross-references; merged with Australian guidance into unified principle areas
* **Trademark**: Use of UK Government content does not imply endorsement

### Australian ASD/ACSC Secure by Design Foundations

* **Copyright**: © Commonwealth of Australia, Australian Signals Directorate
* **License**: [Creative Commons Attribution 4.0 (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/)
* **Source**: https://www.cyber.gov.au/business-government/secure-design/secure-by-design/secure-by-design-foundations
* **Modifications**: Synthesized into structured principle-checklist format with cross-references; merged with UK guidance into unified principle areas
* **Trademark**: Use of ASD/ACSC content does not imply endorsement

[WilliamBerryiii]

Two issues with the content_based_on field:

1. Schema type conflict: PR chore(licensing): update security instruction attributions and compliance #1294 defines content_based_on as "type": "string" in the skill frontmatter schema. This array format will conflict with that schema validation. Consider using a single SPDX-style string or aligning with whatever format PR chore(licensing): update security instruction attributions and compliance #1294 settles on.

2. Missing metadata fields: PR chore(licensing): update security instruction attributions and compliance #1294 standardizes additional metadata fields for skills with third-party content. The following fields should be added once that PR's pattern is finalized:

   • spec_version — the framework/standard version
   • framework_revision — date of the source framework revision
   • last_updated — when the skill content was last synchronized
   • skill_based_on — the upstream skill or source reference

Note: these fields were previously removed per review feedback as "not in VS Code spec," but PR #1294 is adding them to the schema as standard fields for attribution tracking.

[WilliamBerryiii]

The skill content is derived from UK Government material (Crown Copyright, licensed under OGL-UK-3.0) and Australian Government material (© Commonwealth of Australia, licensed under CC-BY-4.0).

The license field should reflect the source material licenses rather than MIT:

license: OGL-UK-3.0 AND CC-BY-4.0

See PR #1294 for the licensing compliance pattern being standardized across all skills with third-party derived content.

[WilliamBerryiii]

All 12 reference files (00-principle-index.md through 11-secure-deprecation.md) need attribution footers before the Copilot line. PR #1294 establishes the pattern:

---

> Content derived from works by the **UK Government Security Group** (Crown Copyright) licensed
> under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
> and the **Australian Signals Directorate / ACSC** (© Commonwealth of Australia) licensed under
> [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
> Modifications: Synthesized into structured principle-checklist format with OWASP cross-references;
> merged UK and AU guidance into unified principle areas.

*🤖 Crafted with precision by ✨Copilot ...*

This applies to all 12 reference files in this skill.