From 2dc168655fb457b106df84e48926b852362f911e Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Tue, 26 May 2026 23:01:09 -0400 Subject: [PATCH] Add skill/command lint and restore truncated command descriptions A generation step had truncated nine command descriptions at ~200 characters, cutting them mid-sentence. Each commands/*.md description is restored to match its SKILL.md source, so the slash-command menu shows the full text and skill and command stay in sync. Adds a zero-dependency node:test suite (tests/skill-lint.test.mjs) that enforces the invariants going forward: directory name matches the frontmatter name and slug regex, description length within 1..1024 and not truncated, SKILL.md body under 500 lines, and each command inlines its SKILL.md body, shares its description, and ends with $ARGUMENTS. A GitHub Actions workflow runs the suite on every push and pull request. --- .github/workflows/ci.yml | 16 ++++++++++ commands/agents-md-revise.md | 2 +- commands/code-architect.md | 2 +- commands/code-explorer.md | 2 +- commands/code-review.md | 2 +- commands/code-reviewer.md | 2 +- commands/feature-dev.md | 2 +- commands/frontend-design.md | 2 +- commands/mcp-builder.md | 2 +- commands/skill-creator.md | 2 +- package.json | 3 ++ tests/skill-lint.test.mjs | 59 ++++++++++++++++++++++++++++++++++++ 12 files changed, 87 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 tests/skill-lint.test.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..1543238 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,16 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + +jobs: + lint-skills: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "lts/*" + - run: node --test diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md index 6235030..af9c5b2 100644 --- a/commands/agents-md-revise.md +++ b/commands/agents-md-revise.md @@ -1,5 +1,5 @@ --- -description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.m +description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. --- # AGENTS.md / CLAUDE.md Revise diff --git a/commands/code-architect.md b/commands/code-architect.md index b095439..bbc7d61 100644 --- a/commands/code-architect.md +++ b/commands/code-architect.md @@ -1,5 +1,5 @@ --- -description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, +description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. --- # Code Architect diff --git a/commands/code-explorer.md b/commands/code-explorer.md index ddfc385..dcd27e8 100644 --- a/commands/code-explorer.md +++ b/commands/code-explorer.md @@ -1,5 +1,5 @@ --- -description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need +description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". --- # Code Explorer diff --git a/commands/code-review.md b/commands/code-review.md index 9424a8c..fb237eb 100644 --- a/commands/code-review.md +++ b/commands/code-review.md @@ -1,5 +1,5 @@ --- -description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a +description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. --- # Code Review diff --git a/commands/code-reviewer.md b/commands/code-reviewer.md index b4074ab..da05e41 100644 --- a/commands/code-reviewer.md +++ b/commands/code-reviewer.md @@ -1,5 +1,5 @@ --- -description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly +description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. --- # Code Reviewer diff --git a/commands/feature-dev.md b/commands/feature-dev.md index b73a73c..51550af 100644 --- a/commands/feature-dev.md +++ b/commands/feature-dev.md @@ -1,5 +1,5 @@ --- -description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when t +description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. --- # Feature Development diff --git a/commands/frontend-design.md b/commands/frontend-design.md index 8df4944..25ad055 100644 --- a/commands/frontend-design.md +++ b/commands/frontend-design.md @@ -1,5 +1,5 @@ --- -description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code +description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. --- This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. diff --git a/commands/mcp-builder.md b/commands/mcp-builder.md index 5972f92..93f255f 100644 --- a/commands/mcp-builder.md +++ b/commands/mcp-builder.md @@ -1,5 +1,5 @@ --- -description: Guide the creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when the user wants to build an MCP server +description: Guide the creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when the user wants to build an MCP server to integrate an external API or service, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). --- ## Overview diff --git a/commands/skill-creator.md b/commands/skill-creator.md index bc221e8..96bb4d1 100644 --- a/commands/skill-creator.md +++ b/commands/skill-creator.md @@ -1,5 +1,5 @@ --- -description: Create new skills (SKILL.md files), modify and improve existing skills, and design skill descriptions for accurate triggering. Use when the user wants to create a new skill from scratch, edit an exist +description: Create new skills (SKILL.md files), modify and improve existing skills, and design skill descriptions for accurate triggering. Use when the user wants to create a new skill from scratch, edit an existing skill, optimize a skill's description, or convert a workflow they just demonstrated into a reusable skill. --- # Skill Creator diff --git a/package.json b/package.json index 9776356..7c4665a 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,9 @@ "description": "Curated bundle of Claude Code skills ported to OpenCode: code-review, feature-dev, security-review, frontend-design, mcp-builder, skill-creator, and the feature-dev sub-agents.", "type": "module", "main": ".opencode/plugins/opencode-power-pack.js", + "scripts": { + "test": "node --test" + }, "license": "MIT", "author": "Wayner Barrios", "repository": { diff --git a/tests/skill-lint.test.mjs b/tests/skill-lint.test.mjs new file mode 100644 index 0000000..cb457d4 --- /dev/null +++ b/tests/skill-lint.test.mjs @@ -0,0 +1,59 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readdirSync, readFileSync, existsSync } from "node:fs"; +import { join } from "node:path"; + +const REPO = process.env.REPO || process.cwd(); +const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/; +const SENTENCE_END = /[.!?"'\)\]]$/; + +function parse(md) { + const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/); + const fm = {}; + if (m) { + for (const line of m[1].split(/\r?\n/)) { + const i = line.indexOf(":"); + if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim(); + } + } + return { fm, body: m ? m[2] : md, hasFrontmatter: !!m }; +} + +const norm = (s) => s.replace(/\s+/g, " ").trim(); + +const skillsDir = join(REPO, "skills"); +const names = readdirSync(skillsDir).filter((n) => + existsSync(join(skillsDir, n, "SKILL.md")) +); + +for (const name of names) { + const skill = parse(readFileSync(join(skillsDir, name, "SKILL.md"), "utf8")); + const cmdPath = join(REPO, "commands", `${name}.md`); + + test(`${name}: SKILL.md frontmatter`, () => { + assert.ok(skill.hasFrontmatter, "has YAML frontmatter"); + assert.equal(skill.fm.name, name, "name matches the directory"); + assert.match(skill.fm.name ?? "", NAME_RE, "name matches the slug regex"); + const d = skill.fm.description ?? ""; + assert.ok(d.length >= 1 && d.length <= 1024, `description length 1..1024 (is ${d.length})`); + assert.ok((skill.fm.license ?? "").length > 0, "license present"); + }); + + test(`${name}: SKILL.md body under 500 lines`, () => { + assert.ok(skill.body.split(/\r?\n/).length < 500); + }); + + test(`${name}: command in sync with SKILL.md`, () => { + assert.ok(existsSync(cmdPath), `commands/${name}.md exists`); + const cmd = parse(readFileSync(cmdPath, "utf8")); + assert.equal(cmd.fm.description, skill.fm.description, "description identical skill<->command"); + assert.ok(norm(cmd.body).includes(norm(skill.body)), "command inlines the SKILL.md body"); + assert.match(cmd.body, /\$ARGUMENTS\s*$/, "command ends with $ARGUMENTS"); + }); + + test(`${name}: descriptions not truncated`, () => { + assert.match((skill.fm.description ?? "").trim(), SENTENCE_END, "SKILL.md description not truncated"); + const cmd = parse(readFileSync(cmdPath, "utf8")); + assert.match((cmd.fm.description ?? "").trim(), SENTENCE_END, "command description not truncated"); + }); +}