Quality Check
Run the skills-for-fabric local quality checker on every skill under skills/ before you open a PR so structure, references, and semantics pass CI.
Overview
Quality-check is an agent skill most often used in Build (also Ship) that runs the skills-for-fabric local quality checker to validate skills before you submit a PR.
Install
npx skills add https://github.com/microsoft/skills-for-fabric --skill quality-checkWhat is this skill?
- Runs python .github/workflows/quality_checker.py from the skills-for-fabric repository root
- Exit codes: 0 pass or warnings only, 1 critical issues block PR, 2 script error
- Writes quality-report.json with overall_status PASSED, WARNING, or CRITICAL plus counts
- Checks structural compliance, semantic disambiguation, broken references, and content quality
- Triggers align with pre-commit workflows: check my skills, lint skills, validate skills
- Exit codes 0, 1, and 2 documented for the quality checker run
Adoption & trust: 28 installs on skills.sh; 427 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You changed one or more agent skills and need to catch structural, semantic, and reference failures before CI rejects your pull request.
Who is it for?
Contributors actively editing skills in the skills-for-fabric repo who want the same gates locally that GitHub Actions enforces.
Skip if: Projects outside skills-for-fabric that expect a portable SKILL.md linter without that repo’s quality_checker.py path.
When should I use this skill?
Triggers include check my skills, run quality check, validate skills, pre-commit check, or lint skills before a skills-for-fabric PR.
What do I get? / Deliverables
You get a quality-report.json and a clear pass or critical exit code so only compliant skills land in the PR.
- quality-report.json with overall_status and issue counts
- Terminal exit code indicating PR readiness
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build → Agent tooling because the skill exists to validate agent skill packages you author in the Fabric skills repo. Agent-tooling is where skill markdown, YAML frontmatter, and cross-skill references are created—exactly what the checker enforces.
Where it fits
After authoring a new Fabric skill, run the checker so frontmatter and folder structure match repo rules.
Before opening a PR, confirm exit code 0 so reviewers only see warning-level nits in quality-report.json.
Validate that cross-links between skills resolve before you publish updated reference docs in the same commit.
How it compares
Repo-specific pre-PR gate for Fabric skills, not a general markdown or OpenAPI linter.
Common Questions / FAQ
Who is quality-check for?
Solo builders and maintainers authoring or updating skills in the skills-for-fabric repository who need fast feedback before review.
When should I use quality-check?
After adding or modifying a skill in Build agent-tooling, and again in Ship review immediately before you create or update a PR.
Is quality-check safe to install?
It instructs running a local Python script from the repo; review the Security Audits panel on this page and inspect .github/workflows/quality_checker.py before executing.
SKILL.md
READMESKILL.md - Quality Check
# Local Quality Check Run quality checks on all skills before committing to catch issues early. ## When to Use - Before creating a PR with skill changes - After adding or modifying a skill - To validate cross-references and semantic conflicts ## Prerequisites Ensure Python 3.8+ and dependencies are installed: ```bash pip install PyYAML requests ``` ## Running the Check ### From Repository Root ```bash # Navigate to skills-for-fabric root cd /path/to/skills-for-fabric # Run quality checker python .github/workflows/quality_checker.py ``` ### PowerShell (Windows) ```powershell cd C:\path\to\skills-for-fabric python .github\workflows\quality_checker.py ``` ## Understanding Results ### Exit Codes | Code | Meaning | |------|---------| | 0 | All checks passed (or only warnings) | | 1 | Critical issues found - must fix before PR | | 2 | Script error | ### Output Report The checker creates `quality-report.json` with detailed findings. Key sections: ```json { "overall_status": "PASSED|WARNING|CRITICAL", "critical_count": 0, "warning_count": 3, "semantic_conflicts": [], "duplicate_triggers": [], "broken_references": [], "structural_issues": [], "content_warnings": [], "skills": { ... } } ``` ## Quality Checks Performed ### Critical (Must Fix) | Check | What It Validates | |-------|-------------------| | YAML Frontmatter | `name` and `description` fields present | | Description Length | Description ≤ 1023 characters | | Update Notice | Blockquote with update check instructions | | Cross-References | All `[text](path)` links resolve to existing files | | Trigger Uniqueness | No duplicate trigger phrases across skills | | Semantic Disambiguation | Descriptions don't overlap >70% with other skills | ### Warnings (Should Fix) | Check | What It Validates | |-------|-------------------| | Description Length Warning | Description approaching limit (≥ 900 chars) | | Must/Prefer/Avoid | Guidance sections present | | Examples | Code examples or prompt/response pairs | | Code Block Tags | Language tags on fenced code blocks | | Description Quality | Mentions technologies | | Naming Convention | Follows `{endpoint}-authoring/consumption-{access}` | | External Links | URLs are accessible (sampled) | ## Fixing Common Issues ### Missing Frontmatter Add at the top of SKILL.md: ```yaml --- name: my-skill-name description: > Clear description ... --- ``` ### Missing Update Notice Add after frontmatter: ```markdown > **Update Check — ONCE PER SESSION (mandatory)** > The first time this skill is used in a session, run the **check-updates** skill before proceeding. > - **GitHub Copilot CLI / VS Code**: invoke the `check-updates` skill. > - **Claude Code / Cowork / Cursor / Windsurf / Codex**: compare local vs remote package.json version. > - Skip if the check was already performed earlier in this session. > **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering ``` ### Broken Reference Check the path exists. Common mistake: - Wrong: `../sqlep-consumption-cli/SKILL.md` - Right: `../sqldw-consumption-cli/SKILL.md` ### Untagged Code Block Add language after opening fence: - Wrong: ` ``` ` - Right: ` ```bash ` or ` ```sql ` ### Semantic Conflict Differentiate your skill's description from the conflicting skill. Make trigger phrases unique. ## Mus