Skill quality audit: line count violations, missing references, and maintainer inconsistencies

Overview

Automated audit of all skills surfaced 30 issues across three categories. This issue tracks the work needed to bring all skills into compliance with the standards defined in CLAUDE.md and CONTRIBUTE.md.

---

1. Line Count Violations (>500 lines) — HIGH

The following SKILL.md files exceed the 500-line limit. Content should be moved to references/ files using the progressive disclosure pattern.

Skill	Lines	Overage
skills/appsec/api-spectral	708	+208
skills/devsecops/iac-checkov	671	+171
skills/offsec/analysis-tshark	638	+138
skills/offsec/recon-nmap	635	+135
skills/devsecops/container-hadolint	598	+98
skills/threatmodel/pytm	574	+74
skills/offsec/network-netcat	566	+66
skills/incident-response/detection-sigma	505	+5
skills/offsec/crack-hashcat	509	+9

Fix: Move detailed workflows, patterns, and advanced sections to references/ and link them from SKILL.md. Keep the main file focused on: overview, quick start, core workflow summary, and resource links.

---

2. Missing Reference Files — MEDIUM

These files are linked from SKILL.md but do not exist on disk, causing broken references:

Skill	Missing File
skills/appsec/api-spectral	references/custom_functions.md
skills/appsec/api-spectral	references/ruleset_patterns.md
skills/appsec/sast-semgrep	references/custom_rules.md
skills/devsecops/container-hadolint	references/cis_mapping.md
skills/devsecops/container-hadolint	references/remediation_guide.md
skills/devsecops/container-hadolint	references/shellcheck_integration.md
skills/devsecops/sca-trivy	references/false_positives.md
skills/devsecops/sca-trivy	references/remediation_guide.md
skills/devsecops/sca-trivy	references/scanner_types.md
skills/threatmodel/pytm	references/component_library.md
skills/threatmodel/pytm	references/risk_matrix.md
skills/threatmodel/pytm	references/stride_methodology.md

Fix: Either create the missing reference files with appropriate content, or remove the dead links from SKILL.md.

---

3. Maintainer Field Inconsistencies — MEDIUM

The maintainer field uses three different formats across the repo. The majority use a bare username (SirAppSec); the following deviate:

Email format (should be username):

• skills/offsec/analysis-tshark — sirappsec@gmail.com
• skills/offsec/crack-hashcat — sirappsec@gmail.com
• skills/offsec/network-netcat — sirappsec@gmail.com
• skills/offsec/pentest-metasploit — sirappsec@gmail.com
• skills/offsec/recon-nmap — sirappsec@gmail.com
• skills/offsec/webapp-nikto — sirappsec@gmail.com
• skills/offsec/webapp-sqlmap — sirappsec@gmail.com

Different username:

• skills/secsdlc/reviewdog — asrour
• skills/secsdlc/sast-horusec — asrour

Fix: Standardize all entries to the username-only format (e.g., SirAppSec). Document the policy in CONTRIBUTE.md.

---

Suggested Follow-up

• Add a line-count check to validate_skill.py so CI catches violations automatically
• Add a reference-file existence check to validate_skill.py
• Document the accepted maintainer format in CONTRIBUTE.md and enforce it in the validator
• Consider a pre-commit hook that runs validate_skill.py on changed skill directories

---

What Passed ✓

For completeness, the following checks found no issues:

• All required frontmatter fields present across all skills
• All descriptions include a "Use when:" clause
• All category values are valid
• All skill directories use kebab-case naming
• No forbidden files (README.md, CHANGELOG.md) in skill directories
• All scripts are executable with proper shebangs
• No placeholder text (TODO/FIXME) in any SKILL.md
• All 29 skills registered in marketplace.json
• marketplace.json is valid JSON