@pigcloud/skills 1.0.0

package/scripts/validate-skill-shapes.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.join(__dirname, '..');
+const skillsRoot = path.join(repoRoot, 'skills');
+const enhancedTemplateSkills = new Set([
+  'spec-refinement',
+  'technical-design',
+  'feature-build',
+  'code-review',
+  'security-review',
+  'performance-check',
+]);
+const enhancedSections = [
+  '## Quick Start',
+  '## Inputs / Outputs',
+  '## Gotchas',
+];
+const shortTemplateSections = [
+  '## Quick Start',
+  '## Inputs / Outputs',
+  '## Gotchas',
+];
+
+function readSkillDirectories() {
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== 'references')
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function readSkillFile(skillName) {
+  return fs.readFileSync(path.join(skillsRoot, skillName, 'SKILL.md'), 'utf8');
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : '';
+}
+
+function extractHeadings(content) {
+  return content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^##\s+/.test(line))
+    .map((line) => line);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function ensureFrontmatterKeys(skillName, frontmatter) {
+  const requiredKeys = [
+    'name:',
+    'description:',
+    'lifecycle_stage:',
+    'dependencies:',
+    'triggers:',
+    'inputs:',
+    'outputs:',
+    'workflow:',
+    'gates:',
+    'refs:',
+    'rule_profile:',
+  ];
+
+  for (const key of requiredKeys) {
+    assert(frontmatter.includes(key), `${skillName}: missing frontmatter key ${key}`);
+  }
+}
+
+function ensureSectionOrder(skillName, headings, requiredOrder) {
+  let lastIndex = -1;
+  for (const section of requiredOrder) {
+    const index = headings.indexOf(section);
+    assert(index >= 0, `${skillName}: missing section ${section}`);
+    assert(index > lastIndex, `${skillName}: section order is invalid around ${section}`);
+    lastIndex = index;
+  }
+}
+
+function validateSkill(skillName) {
+  const content = readSkillFile(skillName);
+  const frontmatter = extractFrontmatter(content);
+  assert(frontmatter, `${skillName}: missing frontmatter`);
+  ensureFrontmatterKeys(skillName, frontmatter);
+
+  const headings = extractHeadings(content);
+  const requiredOrder = enhancedTemplateSkills.has(skillName)
+    ? [
+      '## Purpose',
+      '## Suitable / Unsuitable',
+      '## Quick Start',
+      '## Inputs / Outputs',
+      '## Workflow',
+      '## Replay Signals',
+      '## Gotchas',
+      '## Stop Rules',
+      '## References',
+    ]
+    : [
+      '## Purpose',
+      '## Suitable / Unsuitable',
+      '## Workflow',
+      '## Replay Signals',
+      '## Stop Rules',
+      '## References',
+    ];
+
+  ensureSectionOrder(skillName, headings, requiredOrder);
+
+  if (enhancedTemplateSkills.has(skillName)) {
+    for (const section of enhancedSections) {
+      assert(headings.includes(section), `${skillName}: missing enhanced section ${section}`);
+    }
+  } else {
+    for (const section of shortTemplateSections) {
+      assert(!headings.includes(section), `${skillName}: short template should not include ${section}`);
+    }
+  }
+}
+
+function main() {
+  for (const skillName of readSkillDirectories()) {
+    validateSkill(skillName);
+  }
+
+  console.log('=== Skill shape validation complete ===');
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/validate-skill-stop-rules.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.join(__dirname, '..');
+const skillsRoot = path.join(repoRoot, 'skills');
+
+function readSkillDirectories() {
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== 'references')
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function readSkillFile(skillName) {
+  const skillFile = path.join(skillsRoot, skillName, 'SKILL.md');
+  return fs.readFileSync(skillFile, 'utf8');
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : '';
+}
+
+function extractSectionList(block, sectionName) {
+  const lines = block.split(/\r?\n/);
+  const items = [];
+  let inSection = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!inSection) {
+      if (line === `${sectionName}:`) {
+        inSection = true;
+      }
+      continue;
+    }
+
+    if (!line.startsWith('- ')) {
+      if (line.length === 0) {
+        continue;
+      }
+      break;
+    }
+
+    items.push(line.slice(2).trim());
+  }
+
+  return items;
+}
+
+function extractStopRules(content) {
+  const lines = content.split(/\r?\n/);
+  const items = [];
+  let inSection = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!inSection) {
+      if (line === '## Stop Rules') {
+        inSection = true;
+      }
+      continue;
+    }
+
+    if (line.startsWith('## ')) {
+      break;
+    }
+
+    if (line.startsWith('- ')) {
+      items.push(line.slice(2).trim());
+    }
+  }
+
+  return items;
+}
+
+function normalize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/[^\p{L}\p{N}\s-]+/gu, '')
+    .trim();
+}
+
+function hasMatchingRule(gate, stopRules) {
+  const normalizedGate = normalize(gate);
+  return stopRules.some((rule) => {
+    const normalizedRule = normalize(rule);
+    return normalizedRule.includes(normalizedGate) || normalizedGate.includes(normalizedRule);
+  });
+}
+
+function validateSkill(skillName) {
+  const content = readSkillFile(skillName);
+  const frontmatter = extractFrontmatter(content);
+  if (!frontmatter) {
+    throw new Error(`${skillName}: missing frontmatter`);
+  }
+
+  const gates = extractSectionList(frontmatter, 'gates');
+  const stopRules = extractStopRules(content);
+
+  if (!gates.length) {
+    throw new Error(`${skillName}: missing gates`);
+  }
+
+  if (!stopRules.length) {
+    throw new Error(`${skillName}: missing Stop Rules section`);
+  }
+
+  const missing = gates.filter((gate) => !hasMatchingRule(gate, stopRules));
+  if (missing.length > 0) {
+    throw new Error(`${skillName}: stop rules do not cover gates: ${missing.join(' | ')}`);
+  }
+
+  return {
+    skillName,
+    gates,
+    stopRules,
+  };
+}
+
+function main() {
+  const skills = readSkillDirectories();
+  for (const skillName of skills) {
+    validateSkill(skillName);
+  }
+
+  console.log(`=== Stop rule validation complete for ${skills.length} skills ===`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/validate-skills.cmd

@@ -0,0 +1,3 @@
+@echo off
+setlocal
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0validate-skills.ps1" %*

package/scripts/validate-skills.ps1

@@ -0,0 +1,42 @@
+param(
+    [string]$SkillsRoot
+)
+
+$ErrorActionPreference = 'Stop'
+$repoRoot = (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..')).Path
+$python = Join-Path $repoRoot '.tools\python.cmd'
+if (-not $SkillsRoot) {
+    if (Test-Path -LiteralPath (Join-Path $repoRoot 'skills')) {
+        $SkillsRoot = Join-Path $repoRoot 'skills'
+    } else {
+        $SkillsRoot = Join-Path $repoRoot '.agents\skills'
+    }
+}
+$codexHome = $env:CODEX_HOME
+if (-not $codexHome) {
+    $codexHome = Join-Path $HOME '.codex'
+}
+$validator = Join-Path (Join-Path $codexHome 'skills') '.system\skill-creator\scripts\quick_validate.py'
+
+if (-not (Test-Path -LiteralPath $validator)) {
+    throw "Validator not found: $validator"
+}
+
+$skillsRoot = (Resolve-Path -LiteralPath $SkillsRoot).Path
+$skillDirs = Get-ChildItem -LiteralPath $skillsRoot -Directory
+
+Write-Host "=== Validating skills under $skillsRoot ==="
+$env:PYTHONUTF8 = '1'
+
+foreach ($skillDir in $skillDirs) {
+    $skillFile = Join-Path $skillDir.FullName 'SKILL.md'
+    if (-not (Test-Path -LiteralPath $skillFile)) {
+        Write-Host "SKIP  $($skillDir.Name) (no SKILL.md)"
+        continue
+    }
+
+    Write-Host "VALIDATE $($skillDir.Name)"
+    & $python $validator $skillDir.FullName
+}
+
+Write-Host "=== Validation complete ==="

package/scripts/validate-skills.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+python_cmd="$repo_root/.tools/python.sh"
+codex_home="${CODEX_HOME:-$HOME/.codex}"
+validator="$codex_home/skills/.system/skill-creator/scripts/quick_validate.py"
+if [ -n "${1:-}" ]; then
+  skills_root="$1"
+elif [ -d "$repo_root/skills" ]; then
+  skills_root="$repo_root/skills"
+else
+  skills_root="$repo_root/.agents/skills"
+fi
+
+if [ ! -f "$validator" ]; then
+  echo "Validator not found: $validator" >&2
+  exit 1
+fi
+
+export PYTHONUTF8=1
+
+echo "=== Validating skills under $skills_root ==="
+
+find "$skills_root" -mindepth 1 -maxdepth 1 -type d | sort | while IFS= read -r skill_dir; do
+  skill_file="$skill_dir/SKILL.md"
+  if [ ! -f "$skill_file" ]; then
+    echo "SKIP  $(basename "$skill_dir") (no SKILL.md)"
+    continue
+  fi
+
+  echo "VALIDATE $(basename "$skill_dir")"
+  "$python_cmd" "$validator" "$skill_dir"
+done
+
+echo "=== Validation complete ==="

package/skills/api-docs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: api-docs
+description: Document stable API behavior, request and response contracts, and examples when endpoints need reusable reference docs
+lifecycle_stage: capture
+rule_profile: api
+dependencies:
+  - spec-refinement
+triggers:
+  - API docs
+  - contract
+  - endpoint
+  - request response
+  - OpenAPI
+  - API reference
+inputs:
+  - interface behavior
+  - endpoint list
+  - request and response shapes
+outputs:
+  - API document
+  - contract notes
+  - examples
+workflow:
+  - extract endpoint behavior
+  - write request and response contracts
+  - include examples and constraints
+  - hand off an API document to knowledge-capture
+gates:
+  - stop at documentation
+  - do not change implementation
+  - do not rewrite product scope
+refs:
+  - skills/references/rule-loading-map.md
+  - skills/references/prompt-replay-checklist.md
+  - skills/references/full-chain-replay-scenarios.md
+  - rules/index.md
+---
+
+# API Docs
+
+## Purpose
+
+Write clear API documentation and contracts for already defined behavior.
+
+## Suitable / Unsuitable
+
+- Suitable: endpoint docs, request/response contracts, examples, API notes
+- Unsuitable: implementation changes, product scope changes, rewrite of behavior
+
+## Workflow
+
+1. Extract endpoint behavior.
+2. Write request and response contracts.
+3. Include examples and constraints.
+4. Hand off an API document to `knowledge-capture`.
+
+## Replay Signals
+
+- Input signal: interface behavior, endpoint list, request and response shapes.
+- Output to verify: API document, contract notes, examples.
+- Stop signal: implementation changes or product scope changes.
+- Handoff signal: an API document is ready for `knowledge-capture`.
+
+## Stop Rules
+
+- Stop at documentation.
+- Do not change implementation.
+- Do not rewrite product scope.
+- Do not turn the task into implementation notes.
+
+## References
+
+- `skills/references/rule-loading-map.md`
+- `skills/references/prompt-replay-checklist.md`
+- `skills/references/full-chain-replay-scenarios.md`
+- `rules/index.md`

package/skills/code-review/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: code-review
+description: Review a diff or pull request for correctness, maintainability, and regression risk when a generic code review is needed
+lifecycle_stage: review
+rule_profile: code
+dependencies:
+  - feature-build
+triggers:
+  - diff
+  - pull request
+  - review
+  - quality gate
+  - checklist
+  - code review
+inputs:
+  - diff
+  - pull request
+  - changed files
+outputs:
+  - findings
+  - severity
+  - fix recommendation
+  - evidence summary
+  - review summary
+workflow:
+  - lock the review scope
+  - identify the tech stack and load the matching review overlay(s)
+  - inspect correctness, maintainability, and regression risk
+  - route security-specific issues to `security-review`
+  - route performance-specific issues to `performance-check`
+  - rank findings by severity
+  - produce an actionable review report
+gates:
+  - stop at review findings
+  - do not rewrite code
+  - do not perform implementation refactors
+  - do not become a general design discussion
+refs:
+  - skills/references/rule-loading-map.md
+  - skills/references/flow-test-cases.md
+  - skills/references/full-chain-replay-scenarios.md
+  - skills/references/prompt-replay-checklist.md
+  - skills/code-review/references/rules.md
+  - skills/code-review/references/findings-template.md
+  - skills/code-review/references/stack-notes.md
+  - rules/index.md
+---
+
+# Code Review
+
+## Purpose
+
+Review a change set and return actionable findings.
+
+## Suitable / Unsuitable
+
+- Suitable: PR review, diff review, quality gate, regression check, generic code quality review across Java, Vue, and mixed-stack changes
+- Unsuitable: implementation work, refactoring, broad design discussion, security-specific review, performance-specific review, requirement rewriting
+
+## Quick Start
+
+- Lock the review scope before reading details.
+- Identify the stack(s) first. This repository may apply Java, Vue, or mixed-stack review overlays.
+- Read the diff with the current rules bundle in mind.
+- Report findings with severity and a concrete fix path.
+- If the issue is clearly about auth, secrets, or exposure, hand off to `security-review`.
+- If the issue is clearly about latency, throughput, or resource usage, hand off to `performance-check`.
+- Keep stack-specific concerns in the matching overlay and keep the core review generic.
+
+## Report Format
+
+- Use one entry per finding.
+- Include `location`, `severity`, `evidence`, `why it matters`, and `fix recommendation`.
+- When a stack overlay applies, anchor the finding to the smallest stack-specific surface:
+  - Java: controller, service, entity, mapper, DTO / VO, or MyBatis XML symbol
+  - Vue: component, composable, state module, template, or frontend build file
+  - TypeScript: typed utility, module boundary, state module, or TS config symbol
+- Keep the review summary short when the change is acceptable.
+- If there are no findings, explain why the change is acceptable and what was checked.
+- Separate must-fix findings from optional suggestions.
+
+## Inputs / Outputs
+
+- Inputs:
+  - diff
+  - pull request
+  - changed files
+- Outputs:
+  - findings
+  - severity
+  - fix recommendation
+  - evidence summary
+
+## Workflow
+
+1. Lock the review scope.
+2. Identify the stack overlays and load the matching review baseline(s) when applicable.
+3. Inspect correctness, maintainability, and regression risk.
+4. Route security-specific issues to `security-review`.
+5. Route performance-specific issues to `performance-check`.
+6. Rank findings by severity.
+7. Produce an actionable review report.
+
+## Replay Signals
+
+- Input signal: diff, PR, changed files, or quality gate request.
+- Output to verify: findings, severity, fix recommendation, evidence summary, review summary.
+- Stop signal: rewriting code, implementation refactors, or broad design discussion.
+- Handoff signal: findings are ready for `knowledge-capture`.
+
+## Gotchas
+
+- Do not turn review into implementation work.
+- Do not broaden the scope beyond the submitted change.
+- Do not produce findings without concrete evidence.
+- Do not hide severity or fix recommendation.
+- Do not keep security or performance findings inside generic code review when a specialized review skill fits better.
+- Do not turn stack-specific rules into a generic design discussion.
+
+## Stop Rules
+
+- Stop at review findings.
+- Do not rewrite code.
+- Do not perform implementation refactors.
+- Do not become a general design discussion.
+- Do not turn review into a design task.
+
+## References
+
+- `skills/references/rule-loading-map.md`
+- `skills/references/flow-test-cases.md`
+- `rules/review/index.md`
+- `rules/review/code.md`
+- `rules/review/java.md`
+- `rules/review/vue.md`

package/skills/code-review/references/findings-template.md

@@ -0,0 +1,51 @@
+# Code Review Findings Template
+
+## Shared Shape
+
+Use the same top-level fields for every finding:
+
+- `location`
+- `severity`
+- `evidence`
+- `why it matters`
+- `fix recommendation`
+
+## Rules
+
+- One finding should describe one issue.
+- Keep the location as small as possible.
+- Make the evidence concrete enough to verify.
+- Keep the fix recommendation specific enough to act on.
+- If there are no findings, explain what was checked and why the change is acceptable.
+
+## Section Hints
+
+### Java
+
+- Prefer controller, service, entity, mapper, DTO / VO, or MyBatis XML anchors.
+- Name the violated framework contract.
+- If the issue spans layers, name the first layer where the fix should land.
+
+### Vue
+
+- Prefer component, composable, state module, template, or build-file anchors.
+- State whether the issue is rendering, state flow, reactivity, or build configuration.
+- If the issue crosses files, name the owning frontend surface.
+
+### TypeScript
+
+- Prefer typed utility, module boundary, state module, or TS config anchors.
+- State whether the issue is type safety, module shape, async control flow, or shared utility determinism.
+- If the issue is config-related, name the entrypoint or build target that drifts.
+
+### Security
+
+- Prefer endpoint, auth flow, permission boundary, secret path, or exposure path anchors.
+- Call out the violated trust boundary.
+- State the attack path and impacted asset.
+
+### Performance
+
+- Prefer query, cache path, allocation path, concurrency path, or hot loop anchors.
+- State whether the pressure is CPU, memory, network, database, or allocation-related.
+- Name the slower path and the observable impact.