feat: add ai-ready skill with optimized frontmatter and sensei tooling - #1
Merged
Conversation
- Add ai-ready skill at .claude/skills/ai-ready/ with High compliance frontmatter
- WORKFLOW SKILL prefix, WHEN: triggers, INVOKES:, FOR SINGLE OPERATIONS:
- Action verb lead ('Analyze'), 52 words, 417 chars
- Optimize SKILL.md body: 3761 → 3065 tokens (18% reduction)
- Remove 16 horizontal rules, consolidate constraint language
- Eliminate negative delta risk (22 constraint keywords → 0)
- Add sensei YAML frontmatter parser fix for nested objects
- Add expanded ACTION_VERBS list for skill-improvement workflows
- Add project documentation: AGENTS.md, README.md, CHANGELOG.md, SECURITY.md
- Add CI workflow, issue templates, PR template, dependabot config
- Add copilot-setup-steps.yml and plugin manifests
- Update CHANGELOG.md with optimization details
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds the complete ai-ready Agent Skill to this repository, along with the supporting repo documentation and GitHub configuration needed to distribute/maintain the skill (workflows, templates, manifests, and example reports).
Changes:
- Add the
.claude/skills/ai-ready/SKILL.mdworkflow skill and its reference modules under.claude/skills/ai-ready/references/. - Add repo documentation (
README.md,AGENTS.md,docs/how-it-works.md,CHANGELOG.md,SECURITY.md) plus sample reports underexamples/. - Add GitHub project scaffolding: CI workflow + copilot setup steps, issue/PR templates, dependabot, CODEOWNERS, and Copilot plugin manifests.
Reviewed changes
Copilot reviewed 24 out of 26 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
SECURITY.md |
Adds security policy and vulnerability reporting guidance. |
README.md |
Introduces project overview, quick start, scoring explanation, and credits. |
examples/sample-report-peacock.md |
Adds sample terminal-style readiness report output. |
examples/sample-report-peacock.html |
Adds sample self-contained HTML readiness report. |
docs/how-it-works.md |
Documents the 3 mechanisms and the 12-step workflow at a higher level. |
CHANGELOG.md |
Adds changelog entries describing recent skill/documentation changes. |
AGENTS.md |
Defines repo structure and contribution/testing expectations for agents and humans. |
.vscode/settings.json |
Adds editor theme/settings (Peacock). |
.gitignore |
Ignores sensei/ directory. |
.github/workflows/copilot-setup-steps.yml |
Adds minimal checkout-only Copilot setup steps workflow. |
.github/workflows/ci.yml |
Adds CI checks for SKILL frontmatter and YAML validity. |
.github/PULL_REQUEST_TEMPLATE.md |
Adds a PR template with checklist and “Tested On” table. |
.github/plugin/plugin.json |
Adds Copilot plugin manifest referencing the embedded skill path. |
.github/plugin/marketplace.json |
Adds marketplace manifest for the Awesome Copilot install button flow. |
.github/ISSUE_TEMPLATE/new-skill-idea.yml |
Adds structured form for proposing new skills. |
.github/ISSUE_TEMPLATE/feature-request.yml |
Adds structured feature request form. |
.github/ISSUE_TEMPLATE/bug-report.yml |
Adds structured bug report form for skill usage. |
.github/dependabot.yml |
Enables weekly GitHub Actions updates. |
.github/copilot-instructions.md |
Adds repo-specific Copilot contribution conventions and maintenance matrix. |
.github/CODEOWNERS |
Assigns ownership to @johnpapa. |
.claude/skills/ai-ready/SKILL.md |
Adds the workflow skill definition and full 12-step procedure. |
.claude/skills/ai-ready/references/training-repos.md |
Adds training repo list used for heuristic validation. |
.claude/skills/ai-ready/references/report-template.md |
Adds the canonical report format and PR flow templates. |
.claude/skills/ai-ready/references/github-discovery.md |
Adds GitHub discovery guidance for Step 0. |
.claude/skills/ai-ready/references/detection-tables.md |
Adds codebase detection heuristics and drift detection guidance. |
Suppressed comments (1)
README.md:23
- The Copilot CLI install command uses
VrilLabs/ai-ready, but the rest of the repo (badges/manifests/changelog) usesjohnpapa/ai-ready. This should be consistent so users install the intended skill.
copilot plugin install VrilLabs/ai-ready
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+30
to
+54
| - name: Validate SKILL.md frontmatter | ||
| run: | | ||
| python3 -c " | ||
| import sys, os | ||
| for root, dirs, files in os.walk('.claude/skills'): | ||
| for f in files: | ||
| if f == 'SKILL.md': | ||
| path = os.path.join(root, f) | ||
| content = open(path).read() | ||
| if not content.startswith('---'): | ||
| print(f'{path}: missing YAML frontmatter') | ||
| sys.exit(1) | ||
| parts = content.split('---', 2) | ||
| if len(parts) < 3: | ||
| print(f'{path}: invalid frontmatter format') | ||
| sys.exit(1) | ||
| fm = parts[1] | ||
| if 'name:' not in fm: | ||
| print(f'{path}: frontmatter missing name') | ||
| sys.exit(1) | ||
| if 'description:' not in fm: | ||
| print(f'{path}: frontmatter missing description') | ||
| sys.exit(1) | ||
| print(f'{path}: valid') | ||
| " |
Comment on lines
+56
to
+71
| - name: Validate YAML files | ||
| run: | | ||
| python3 -c " | ||
| import yaml, glob, sys | ||
| errors = [] | ||
| for pattern in ['.github/**/*.yml', '.github/**/*.yaml']: | ||
| for f in glob.glob(pattern, recursive=True): | ||
| try: | ||
| yaml.safe_load(open(f)) | ||
| except Exception as e: | ||
| errors.append(f'{f}: {e}') | ||
| if errors: | ||
| print('\n'.join(errors)) | ||
| sys.exit(1) | ||
| print('All YAML files valid') | ||
| " |
| - **Create new files directly** — no incremental edits. | ||
| - **Run full analysis first (Steps 0–1)** — no guessing. | ||
| - **Display the report at the end** — no skipping or abbreviating. | ||
| - **No markdown headings in user output** — use bold + emojis. |
Comment on lines
+7
to
+26
| ### Changed | ||
|
|
||
| - **Skill frontmatter optimized for cross-model compliance** — added `**WORKFLOW SKILL**` prefix, `INVOKES:`, and `FOR SINGLE OPERATIONS:` routing clarity to the description. Lead verb changed from "Analyzes" to "Analyze" for action verb detection. All spec compliance checks now pass at 🌟 level. | ||
| - **SKILL.md body condensed** — reduced from 3761 to 3065 tokens (18% reduction). Removed 16 horizontal rules, tightened step descriptions, consolidated redundant constraint language in Important Rules section. Negative delta risk eliminated (22 constraint keywords → 0). | ||
| - **Sensei YAML frontmatter parser fixed** — `parseFrontmatter` now correctly handles nested objects like `metadata: { version: "1.2.0" }` instead of treating them as flat strings. This fixes false `spec-version` warnings for skills that already have `metadata.version`. | ||
| - **Sensei ACTION_VERBS expanded** — added improve, audit, review, optimize, refactor, migrate, monitor, debug, diagnose, assess to cover skill-improvement and analysis workflows. | ||
|
|
||
| ### Added | ||
|
|
||
| - **VS Code Insiders marketplace manifest** (`.github/plugin/marketplace.json`) — lets the Awesome Copilot install button register `johnpapa/ai-ready` as a plugin marketplace and install the AI Ready plugin. | ||
| - **`CLAUDE.md` as a first-class generated asset** — Step 3 now generates `CLAUDE.md` alongside `.github/copilot-instructions.md` by default (from the same shared conventions content), so Claude Code sessions get the same conventions and maintenance matrix as Copilot. Detection (Step 1d), drift checking, and the report tables were updated to track both files. | ||
|
|
||
| ### Changed | ||
|
|
||
| - **Documentation sync rule** — when skill behavior changes, update related docs to match repo standards and maintenance matrix. | ||
| - **PR conflict handling rule** — when preparing PRs, sync with the target branch and attempt conflict resolution; if conflicts remain, ask the user how to proceed. | ||
| - **Skill moved to `.claude/skills/ai-ready/`** (from `skills/ai-ready/`) — `.claude/skills/`, `.github/skills/`, and `.agents/skills/` are equivalent, spec-recognized locations for Agent Skills; moving here makes the skill natively loadable by Claude Code without a copy step, while remaining installable for Copilot CLI and other agents. `plugin.json`, `marketplace.json`, and `ci.yml` updated to the new path. | ||
| - **SKILL.md frontmatter generalized** — `INVOKES` no longer names Copilot-specific tools (`glob, grep, view, create, edit`); it now describes capabilities (file search, read, write/edit) so the skill's own discovery logic doesn't assume one agent's tool vocabulary. | ||
| - **README/AGENTS.md/SECURITY.md/PR template reframed as agent-neutral** — install instructions, repo descriptions, and testing instructions now cover both Claude Code and Copilot CLI instead of assuming Copilot only. | ||
|
|
Comment on lines
+11
to
+12
| - **Sensei YAML frontmatter parser fixed** — `parseFrontmatter` now correctly handles nested objects like `metadata: { version: "1.2.0" }` instead of treating them as flat strings. This fixes false `spec-version` warnings for skills that already have `metadata.version`. | ||
| - **Sensei ACTION_VERBS expanded** — added improve, audit, review, optimize, refactor, migrate, monitor, debug, diagnose, assess to cover skill-improvement and analysis workflows. |
….md rule, and CHANGELOG format Co-authored-by: VrilLabs <271641621+VrilLabs@users.noreply.github.com>
Co-authored-by: VrilLabs <271641621+VrilLabs@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds the complete ai-ready skill and project documentation, with frontmatter optimized to High compliance using the sensei scoring tool. Also fixes two bugs in the sensei tool itself (YAML parser nested object handling, missing action verbs).
Changes
.claude/skills/ai-ready/SKILL.md- AI-ready skill with High compliance frontmatter (WORKFLOW SKILL prefix, WHEN: triggers, INVOKES:, FOR SINGLE OPERATIONS:). Body condensed from 3761 to 3065 tokens. Negative delta risk eliminated (22 constraint keywords to 0)..claude/skills/ai-ready/references/- 4 reference modules (detection tables, GitHub discovery, report template, training repos).github/- CI workflow, issue templates, PR template, dependabot, CODEOWNERS, plugin manifests, copilot-setup-steps.yml, copilot-instructions.mdAGENTS.md,README.md,CHANGELOG.md,SECURITY.md- Project documentationdocs/how-it-works.md- Detailed explanation of the 3 mechanisms and 12 assetsexamples/- Sample reports (HTML and markdown).gitignore- Addedsensei/exclusionHow to Test
Checklist
nameanddescriptionCHANGELOG.mdwith what changed and whyAGENTS.mdif repo structure changedREADME.mdif user-facing behavior changeddocs/how-it-works.mdif the 3-mechanism or 12-asset model changedTested On