Add create-skill command with validation and documentation

[ericelliott]

Overview

This PR introduces the create-skill command and supporting infrastructure for creating new agent skills following the AgentSkills.io specification.

Changes

New Files

• ai/skills/create-skill/SKILL.md - Comprehensive skill definition with:

  • Full specification for creating agent skills
  • Type definitions and interfaces (SkillName, SkillDescription, SizeMetrics, SkillPlan)
  • Step-by-step process for skill creation
  • Validation requirements and constraints
  • Documentation requirements (required sections, size limits)
  • Example SKILL.md template

• ai/skills/create-skill/scripts/validate-skill.js - Validator module exporting:

  • parseSkillMd() - Parses YAML frontmatter and body from SKILL.md content
  • validateName() - Validates skill names (1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, matches directory name)
  • calculateMetrics() - Calculates size metrics (frontmatter tokens, body lines, body tokens)
  • checkThresholds() - Checks against size guidelines (frontmatter < 100 tokens, body < 160 lines / < 500 lines hard limit, < 5000 tokens)

• ai/skills/create-skill/scripts/validate-skill.test.js - Comprehensive unit tests covering:

  • Frontmatter parsing (valid and missing)
  • Name validation (valid names, uppercase, leading/trailing/consecutive hyphens, length, empty, directory mismatch)
  • Metric calculation
  • Threshold checking (all within limits, frontmatter, 160-line, 500-line, 5000-token warnings)

• ai/commands/create-skill.md - Command definition referencing the create-skill skill

• Index files - Navigation and documentation:

  • ai/skills/index.md
  • ai/skills/create-skill/index.md
  • ai/skills/create-skill/scripts/index.md

Modified Files

• ai/commands/index.md - Added create-skill command entry
• ai/index.md - Added skills directory reference
• ai/rules/please.mdc - Added /create-skill command reference
• ai/rules/agent-orchestrator.mdc - Added create-skill reference

Key Features

• Specification-compliant: Implements AgentSkills.io specification with AIDD extensions (e.g., metadata.alwaysApply)
• Comprehensive validation: Name format, size metrics, and threshold warnings
• Well-documented: Includes type definitions, interfaces, process flow, and constraints
• Tested: Full unit test coverage for all validator functions
• Extensible: Supports optional directories (scripts/, references/, assets/) and metadata

Test Plan

Added comprehensive unit tests in validate-skill.test.js covering all validator functions:

• 2 tests for parseSkillMd (valid frontmatter, no frontmatter)
• 8 tests for validateName (valid names, uppercase, hyphens, length, empty, directory mismatch)
• 1 test for calculateMetrics
• 5 tests for checkThresholds (within limits, frontmatter, 160-line, 500-line, 5000-token)

All tests use the riteway/vitest assertion framework and follow project conventions.

https://claude.ai/code/session_012PBVMXigqq6Bd4WTUhi4b7

---

Note

Low Risk
Mostly additive documentation/skill content plus a new validate-skill CLI and tests; limited blast radius outside the ai/ tooling/docs surface area.

Overview
Introduces two new agent skills: aidd-rtc (a structured “show your work” reasoning pipeline) and aidd-upskill (a guide and workflows to create/review skills, including deduplication and function-test criteria).

Adds a Bun/Node-compatible validate-skill CLI (with extensive unit tests) to validate SKILL.md frontmatter/name rules and size thresholds, plus npm scripts to build the compiled binary and run new aidd-upskill eval suites.

Wires the new commands/skills into existing indexes and orchestration (ai/commands/index.md, ai/skills/index.md, aidd-agent-orchestrator, aidd-please, aidd-review), and adds .gitignore coverage for the compiled validator output.

^{Reviewed by Cursor Bugbot for commit cc5ddaf. Bugbot is set up for automated code reviews on this repo. Configure here.}

[ericelliott]

@cursoragent please /review

[Copilot]

Pull request overview

This PR adds a new create-skill capability to the ai/ knowledge/automation layer, including a full skill specification (SKILL.md), a validator module with unit tests, and updates to command/rule indexes so the new skill/command is discoverable.

Changes:

• Added ai/skills/create-skill/SKILL.md defining the “create skill” process, constraints, and documentation requirements.
• Added a JavaScript validator module (validate-skill.js) plus Vitest unit tests (validate-skill.test.js) for parsing/name/size checks.
• Updated ai/ indexes and rules to reference the new skills directory and /create-skill command.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
ai/index.md	Links the new skills/ section from the top-level AI index.
ai/commands/index.md	Adds create-skill to the commands index.
ai/commands/create-skill.md	Defines the /create-skill command and points to the skill guide.
ai/rules/please.mdc	Adds /create-skill to the global command list.
ai/rules/agent-orchestrator.mdc	Adds a create-skill reference to the orchestrator’s guide list.
ai/skills/index.md	Introduces a new skills directory index and links to create-skill/.
ai/skills/create-skill/index.md	Adds an index page describing the create-skill skill and subdirs.
ai/skills/create-skill/SKILL.md	Adds the full skill specification, workflow, constraints, and example template.
ai/skills/create-skill/scripts/index.md	Adds an index for scripts (currently inaccurate per PR contents).
ai/skills/create-skill/scripts/validate-skill.js	Adds validator utilities (currently documented as a CLI but not implemented as one).
ai/skills/create-skill/scripts/validate-skill.test.js	Adds unit tests for the validator utilities.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ianwhitedeveloper]

🔬 Code Review — Final Pass ✅ Approving

All blockers from the initial review have been addressed across the subsequent commits. The 04626e6 YAML refactor was particularly clean — switching from regex + quote-stripping to reading directly from the parsed YAML object resolved BUG-3 more robustly than the targeted fix alone, while also handling inline YAML comments and degenerate (non-mapping) frontmatter in the same pass.

✅ All Previously Flagged Issues — Resolved

Issue	Fix commit
BUG-1: resolveIsMainEntry exported but never called	04626e6
BUG-2: malformed YAML crashed validator instead of returning error	195aca0
BUG-3: name field not quote-stripped (false validation errors)	04626e6 (supersedes 195aca0)
BUG-4: description max 1024-char limit not enforced (spec gap)	cbb3db0
Stale please.mdc reference in command file	bfc2612
README path mismatch (aidd-custom/aidd-[name] vs aidd-custom/skills/aidd-[name])	bfc2612
reportFindings lacked structure	bfc2612
Boundary tests missing for all four checkThresholds thresholds	416ef64
validateName + calculateMetrics tests were boolean checks, not concrete values	b6aef22

---

⚪ Follow-up Recommendations (non-blocking)

These are too small to block merge but worth a follow-up ticket or next-pass cleanup:

1 — validateFrontmatterKeys: replace imperative loop with functional pipeline

Per the project's /aidd-javascript style guide ("favour map, filter, reduce over manual loops"):

// Current:
const errors = [];
for (const key of Object.keys(frontmatterObj)) {
  if (!ALLOWED_FRONTMATTER_KEYS.has(key)) errors.push(…);
}
return errors;

// Recommended:
export const validateFrontmatterKeys = (frontmatterObj) =>
  Object.keys(frontmatterObj)
    .filter((key) => !ALLOWED_FRONTMATTER_KEYS.has(key))
    .map((key) => `Unknown frontmatter key: ${key}`);

2 — Boundary messages: "exceeds" → "reaches or exceeds" at 160 and 500 lines

The frontmatter warning already uses the correct phrasing ("reaches or exceeds 100 token guideline"). The body messages should match for consistency:

// At exactly 160 or 500 lines, these messages are technically inaccurate:
"Body exceeds 500 line spec limit …"   // should be "reaches or exceeds"
"Body exceeds 160 line guideline"      // should be "reaches or exceeds"

3 — process.md validate step: add dev fallback

The validate step calls the compiled binary directly. Agents running this before building will hit a missing-file error. One line resolves it:

# Development (no compiled binary needed):
node ai/skills/aidd-upskill/scripts/validate-skill.js ./path-to-skill-directory

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9e4109b. Configure here.}

[cursor]

Reimplements frontmatter parsing despite existing gray-matter dependency

Low Severity

The parseSkillMd function hand-rolls YAML frontmatter extraction with a regex, but gray-matter (already a project dependency in package.json) does exactly this. gray-matter returns both the parsed data and the raw matter string, so it could replace this custom parser while also providing the raw frontmatter string needed by calculateMetrics.

 

^{Reviewed by Cursor Bugbot for commit 9e4109b. Configure here.}