@guru-ai-product/ai-product-kit 0.2.251117162107 → 0.2.251117163427

package/mcp/skills/aipk_init_project/template/AGENTS_TEMPLATE.md

@@ -55,7 +55,7 @@ Use these MCP tools to load a Skill by name. The server maps known Skill names t
 
 <skill>
 <name>skill-creation</name>
-<description>Standards and methods for creating Agent Skills that extend Claude's capabilities. Use when creating or updating Skills, rules, or documentation that should follow Skill structure.</description>
+<description>Standards and practices for creating new Agent Skills that extend Claude with reusable workflows, documentation, and tooling assets.</description>
 <tool>product_kit_skill</tool>
 <arguments>{"skill_name": "aipk_skill_generate"}</arguments>
 </skill>

package/mcp/src/server.js

@@ -33,7 +33,7 @@ const SKILL_DESCRIPTIONS = {
   "aipk_development": "Development phase index pointing to the single authoritative implementation plan template.",
   "aipk_operations": "Canonical entry point for every post-release operating guide; maps scenarios to the available Skills and explains how to invoke them.",
   "aipk_requirements": "Central repository for requirement discovery, documentation, review, and change management assets.",
-  "aipk_skill_generate": "Standards and methods for creating Agent Skills that extend Claude's capabilities. Use when creating or updating Skills, rules, or documentation that should follow Skill structure.",
+  "aipk_skill_generate": "Standards and practices for creating new Agent Skills that extend Claude with reusable workflows, documentation, and tooling assets.",
   "aipk_tool_prompts": "Catalog of reusable prompts for AI tooling workflows, including their usage guidance and file locations.",
   "aipk_init_project": "Initialize the project Agents playbook, sync the skills inventory into AGENTS.md/templates, and verify the workspace includes a complete AGENTS.md file.",};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guru-ai-product/ai-product-kit",
-  "version": "0.2.251117162107",
+  "version": "0.2.251117163427",
   "description": "Sync the AI Product Kit Skill bundle through npx without cloning the repository.",
   "bin": {
     "ai-product-kit": "bin/setup.js",

package/skills/aipk_design/GURU_AI.md

@@ -1,6 +1,6 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |

package/skills/aipk_development/GURU_AI.md

@@ -1,6 +1,6 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |

package/skills/aipk_init_project/GURU_AI.md

@@ -1,10 +1,10 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |
 | `scripts/check_agents.sh` | 2025-11-13T09:03:47.702Z |
 | `skill.ini` | 2025-11-13T09:47:02.793Z |
 | `SKILL.md` | 2025-11-13T10:06:33.764Z |
-| `template/AGENTS_TEMPLATE.md` | 2025-11-17T08:21:07.865Z |
+| `template/AGENTS_TEMPLATE.md` | 2025-11-17T08:34:27.435Z |

package/skills/aipk_operations/GURU_AI.md

@@ -1,6 +1,6 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |

package/skills/aipk_requirements/GURU_AI.md

@@ -1,6 +1,6 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |

package/skills/aipk_skill_generate/GURU_AI.md

@@ -1,8 +1,10 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |
 | `agent_skills_spec.md` | 2025-11-12T10:41:15.869Z |
-| `SKILL.md` | 2025-11-12T10:41:15.868Z |
+| `scripts/init_skill.js` | 2025-11-17T08:26:29.962Z |
+| `scripts/package_skill.js` | 2025-11-17T08:26:40.891Z |
+| `SKILL.md` | 2025-11-17T08:26:11.887Z |

package/skills/aipk_skill_generate/SKILL.md

@@ -1,259 +1,66 @@
 ---
 name: skill-creation
-description: Standards and methods for creating Agent Skills that extend Claude's capabilities. Use when creating or updating Skills, rules, or documentation that should follow Skill structure.
+description: Standards and practices for creating new Agent Skills that extend Claude with reusable workflows, documentation, and tooling assets.
+license: Complete terms in LICENSE.txt
 ---
 
-# Skill 创建方法
+# Skill Creation Playbook
 
-## 1. 技能定位
+This skill captures the expectations, templates, and workflows used across AI Product Kit to author reusable Skills. Treat it as the canonical reference when you need to convert a document into a Skill, add a new workflow, or refresh existing guidance.
 
-- **适用场景**：创建新的 Agent Skills、将现有文档转换为 Skill 格式、更新项目规则文档
-- **目标人群**：文档撰写者、项目管理者、规则维护者
-- **价值主张**：提供标准化的 Skill 创建规范，确保所有规则和文档遵循统一的 Skill 结构，实现模块化和可重用性
+## 1. Why Skills Matter
 
-## 2. 快速上手
+- **Modular knowledge** – Skills bundle procedures, references, and optional code so Claude can load the precise context it needs.
+- **Stable triggers** – YAML frontmatter metadata (name + description) defines when Claude will pick the Skill, so be deliberate with wording.
+- **Repeatable automation** – Scripts and templates included with a Skill run deterministically, often without loading their contents into the context window.
 
-1. 创建 Skill 目录，目录名与 Skill 名称一致（小写字母、数字和连字符）
-2. 在目录中创建 `SKILL.md` 文件
-3. 添加 YAML frontmatter，包含 `name` 和 `description` 字段
-4. 按照标准章节结构编写 Markdown 内容
-5. 可选：添加额外的资源文件（模板、脚本、参考文档等）
+## 2. Anatomy of a Skill
 
-## 3. Skill 结构规范
-
-### 3.1 必需的文件结构
-
-每个 Skill 必须包含一个 `SKILL.md` 文件，作为 Skill 的入口点：
+Every Skill follows this basic layout:
 
 ```
 my-skill/
-  - SKILL.md
-```
-
-更复杂的 Skill 可以添加额外的目录和文件：
-
-```
-my-skill/
-  ├── SKILL.md (主入口文件)
-  ├── template/
-  │   └── example.md (模板文件)
-  ├── examples/
-  │   └── usage.md (使用示例)
-  └── scripts/
-      └── helper.py (辅助脚本)
-```
-
-### 3.2 SKILL.md 文件格式
-
-#### YAML Frontmatter（必需）
-
-```yaml
----
-name: your-skill-name
-description: 简洁描述技能覆盖的场景、可交付物以及使用时机。
-license: 可选，若需声明许可或合规信息则填写
-metadata:
-  owner: 团队或负责人
-  version: v1.0.0
----
-```
-
-**必需字段**：
-
-- `name`：
-  - Skill 名称，使用连字符命名（hyphen-case）
-  - 仅包含小写字母、数字和连字符
-  - 最大 64 个字符
-  - 不能包含 XML 标签
-  - 不能包含保留词："anthropic", "claude"
-  - 必须与包含 SKILL.md 的目录名称匹配
-
-- `description`：
-  - 简要描述 Skill 的功能和使用时机
-  - 必须非空
-  - 最大 1024 个字符
-  - 不能包含 XML 标签
-  - 应说明 Skill 做什么以及何时使用
-
-**可选字段**：
-
-- `license`：许可信息（简短形式或指向许可文件的名称）
-- `allowed-tools`：预批准运行的工具列表（目前仅在 Claude Code 中支持）
-- `metadata`：键值对映射，用于存储客户端自定义属性
-
-#### Markdown 正文
-
-Markdown 正文部分没有格式限制，但建议遵循项目的文档撰写标准（参见 [`../../docs/guide_writing_standard/SKILL.md`](../../docs/guide_writing_standard/SKILL.md)）。
-
-**推荐章节结构**：
-
-```markdown
-# 技能主标题
-
-## 1. 技能定位
-- **适用场景**：列出该技能最核心的使用场景
-- **目标人群**：说明主要使用角色
-- **价值主张**：突出该技能解决的痛点或提供的能力
-
-## 2. 快速上手
-1. 步骤一…
-2. 步骤二…
-3. 步骤三…
-
-## 3. 标准流程
-| 阶段 | 说明 | 交付物 |
-| ---- | ---- | ------ |
-| 规划 | …    | …      |
-| 执行 | …    | …      |
-| 检查 | …    | …      |
-
-## 4. AI 协作要点
-- 使用的模型或工具
-- 推荐的 Prompt
-- 自动化检查或输出格式要求
-
-## 5. 附加资源
-- [模板链接](./template/示例模板.md)
-- [最佳实践](./examples/XXX.md)
-- [常见问题](./references/FAQ.md)
+├── SKILL.md        (required entrypoint with YAML frontmatter + Markdown guidance)
+├── template/       (optional templates, forms, or content snippets)
+├── scripts/        (optional executable helpers; prefer Node.js if you add new scripts here)
+├── references/     (optional supporting docs)
+└── assets/         (optional files used by Skill outputs)
 ```
 
-## 4. Skill 工作原理
-
-### 4.1 三级加载机制
-
-Skills 采用渐进式加载（progressive disclosure），内容在三个层级加载：
-
-**Level 1: 元数据（始终加载）**
-
-- 内容类型：指令
-- 加载时机：启动时
-- Token 成本：约 100 tokens 每个 Skill
-- 内容：YAML frontmatter 中的 `name` 和 `description`
-
-**Level 2: 指令（触发时加载）**
-
-- 内容类型：指令
-- 加载时机：Skill 被触发时
-- Token 成本：通常低于 5k tokens
-- 内容：SKILL.md 的主体内容，包含工作流程、最佳实践和指导
-
-**Level 3: 资源和代码（按需加载）**
-
-- 内容类型：指令、代码和资源
-- 加载时机：需要时
-- Token 成本：有效无限制（通过 bash 执行，不加载到上下文）
-- 内容：其他 Markdown 文件、可执行脚本、参考材料
-
-### 4.2 文件系统架构
-
-Skills 运行在代码执行环境中，Claude 具有文件系统访问、bash 命令和代码执行能力。Skills 作为目录存在于虚拟机上，Claude 使用 bash 命令与之交互。
-
-**优势**：
-
-- **按需文件访问**：Claude 只读取任务需要的文件
-- **高效的脚本执行**：脚本代码不加载到上下文窗口，只输出消耗 tokens
-- **无实际限制的捆绑内容**：未使用的文件不消耗上下文
-
-## 5. 创建 Skill 的最佳实践
-
-### 5.1 命名规范
-
-- 使用小写字母、数字和连字符
-- 名称应简洁且描述性强
-- 避免使用保留词
-
-### 5.2 描述编写
-
-描述应清晰说明：
-
-- Skill 的功能
-- 使用场景
-- 何时应该触发该 Skill
-
-示例：
-
-```yaml
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
-```
-
-### 5.3 内容组织
-
-- **主文件（SKILL.md）**：包含核心指导和快速上手
-- **附加文件**：将详细参考、模板、示例放在单独文件中
-- **脚本**：将可执行代码放在 scripts/ 目录下
-
-### 5.4 安全性考虑
-
-- 仅使用可信来源的 Skills
-- 审计所有捆绑的文件（SKILL.md、脚本、图像、其他资源）
-- 注意外部数据源的风险
-- 谨慎使用来自未知或不可信来源的 Skills
-
-## 6. 示例参考
-
-### 6.1 最小示例
-
-```
-minimal-skill/
-  - SKILL.md
-```
-
-```markdown
----
-name: minimal-skill
-description: A minimal example Skill demonstrating basic structure.
----
-
-# Minimal Skill
-
-## Quick start
-
-This is a minimal Skill example.
-```
-
-### 6.2 完整示例
-
-参考项目中的现有 Skills：
-
-- [`../../docs/guide_writing_standard/SKILL.md`](../../docs/guide_writing_standard/SKILL.md) - 文档撰写标准
-- [`../requirements/SKILL.md`](../requirements/SKILL.md) - 需求阶段资料库
-- [`../tool_prompts/SKILL.md`](../tool_prompts/SKILL.md) - 工具 Prompt 文档规范
-
-## 7. 工具和环境支持
-
-### 7.1 Claude Code
-
-- 支持自定义 Skills
-- Skills 作为目录结构存在于文件系统中
-- Claude 自动发现和使用它们
+### SKILL.md expectations
 
-### 7.2 Claude API
+1. Start with YAML frontmatter containing `name` and `description`.
+2. Use hyphen-case, lowercase names that match the folder name.
+3. Keep `description` factual—explain what the Skill does and when to use it.
+4. Follow this recommended markdown structure: introduction, quick start, workflow, AI collaboration notes, and appendices.
 
-- 支持预构建的 Agent Skills 和自定义 Skills
-- 需要特定 beta headers
-- 通过 `/v1/skills` 端点上传自定义 Skills
+## 3. Skill creation workflow
 
-### 7.3 Claude Agent SDK
+1. **Discover the need** – Understand the task sequences users will run, capturing examples and desired deliverables.
+2. **Organize reusable content** – Decide what belongs in SKILL.md versus templates, references, or scripts.
+3. **Initialize the directory** – Use `node scripts/init_skill.js <skill-name> --path <output-directory>` to scaffold the required files.
+4. **Document the process** – Describe when to use the Skill, how Claude should apply it, and how to inspect/update its resources.
+5. **Bundle assets** – Add templates, prompts, or scripts (prefer Node.js scripts) that Claude can execute as part of the Skill.
+6. **Validate & iterate** – Run `node scripts/package_skill.js <skill-dir>` to validate structure before integrating.
 
-- 支持文件系统配置的自定义 Skills
-- Skills 位于 `.claude/skills/` 目录
-- 在 `allowed_tools` 配置中包含 `"Skill"` 以启用
+## 4. Loading behavior
 
-### 7.4 Claude.ai
+Skills use progressive disclosure for efficiency:
 
-- 支持预构建和自定义 Skills
-- 自定义 Skills 通过设置上传
-- 需要特定计划和支持代码执行
+- **Level 1 – Metadata:** Always in context (name + description).
+- **Level 2 – Instructions:** Loaded when the Skill is triggered (SKILL.md body).
+- **Level 3 – Resources:** Loaded or executed on-demand (scripts, templates, references).
 
-## 8. 版本历史
+## 5. Writing guidance
 
-- 1.0 (2025-10-16) - Agent Skills Spec 公开发布
-- 1.1 (YYYY-MM-DD) - 整合到 AI Product Kit 项目规范
+- Keep language direct and imperative.
+- Prefer single-topic paragraphs.
+- Cite external references with markdown links that include sources and dates.
+- When describing scripts or automation, call out expected inputs, outputs, and safety considerations.
 
-## 9. 参考资料
+## 6. Best practices
 
-- [Agent Skills 官方文档](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills)
-- [Agent Skills Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills)
-- [Agent Skills Spec](./agent_skills_spec.md) - 技术规范详情
-- [项目文档撰写标准](../../docs/guide_writing_standard/SKILL.md)
+- Keep the Skill purpose narrow—one Skill should solve a single scenario well.
+- Avoid redundancy by linking to existing references or templates when possible.
+- Document any required tools or permissions in the Skill itself.
+- Leave TODO comments when uncertain so the next maintainer can easily spot open questions.

package/skills/aipk_skill_generate/scripts/init_skill.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const USAGE = `
+Usage: node scripts/init_skill.js <skill-name> --path <output-directory>
+
+Example:
+  node scripts/init_skill.js my-new-skill --path skills/aipk_design
+`;
+
+function titleCase(name) {
+  return name
+    .split('-')
+    .map((segment) => segment[0]?.toUpperCase() + segment.slice(1))
+    .join(' ');
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function parseArgs() {
+  const [skillName, ...rest] = process.argv.slice(2);
+  if (!skillName) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+  const pathFlagIndex = rest.indexOf('--path');
+  if (pathFlagIndex === -1 || pathFlagIndex === rest.length - 1) {
+    console.error('Error: Missing --path argument.');
+    console.error(USAGE);
+    process.exit(1);
+  }
+  const basePath = rest[pathFlagIndex + 1];
+  return { skillName, basePath };
+}
+
+function buildSkillTemplate(skillName) {
+  const title = titleCase(skillName);
+  return `---
+name: ${skillName}
+description: [TODO] Describe what ${skillName} does and when Claude should use it.
+---
+
+# ${title}
+
+## Overview
+
+- **Purpose**: [TODO: Summarize the skill intent.]
+- **When to use**: [TODO: Provide trigger scenarios.]
+
+## Quick Start
+
+1. [TODO: Step-by-step guidance.]
+2. [TODO: Reference scripts/templates as needed.]
+
+## Workflow
+
+[TODO: Outline the core workflow or capabilities.]
+
+## Resources
+
+- Templates: \`template/\`
+- Scripts: \`scripts/\`
+- References: \`references/\`
+- Assets: \`assets/\`
+
+`;
+}
+
+function createExampleHelper(skillDir, skillName) {
+  const helperPath = path.join(skillDir, 'scripts', 'example-helper.js');
+  const title = titleCase(skillName);
+  const content = `#!/usr/bin/env node
+/**
+ * Example helper script for ${skillName}
+ * Replace this file with actual automation code if the Skill requires it.
+ */
+
+function main() {
+  console.log('This is a template helper script for ${title}.');
+  console.log('Replace it with real logic or delete when unused.');
+}
+
+main();
+`;
+  fs.writeFileSync(helperPath, content, { encoding: 'utf8', mode: 0o755 });
+}
+
+function createPlaceholder(dir, name, lines) {
+  const target = path.join(dir, name);
+  fs.writeFileSync(target, lines.join('\n'), 'utf8');
+}
+
+function main() {
+  const { skillName, basePath } = parseArgs();
+  const resolvedBase = path.resolve(basePath);
+  ensureDir(resolvedBase);
+  const skillDir = path.join(resolvedBase, skillName);
+  if (fs.existsSync(skillDir)) {
+    console.error(`Skill directory already exists: ${skillDir}`);
+    process.exit(1);
+  }
+  ensureDir(skillDir);
+  const templatePath = path.join(skillDir, 'SKILL.md');
+  fs.writeFileSync(templatePath, buildSkillTemplate(skillName), 'utf8');
+
+  for (const subdir of ['scripts', 'references', 'assets', 'template']) {
+    ensureDir(path.join(skillDir, subdir));
+  }
+
+  createExampleHelper(skillDir, skillName);
+  createPlaceholder(path.join(skillDir, 'references'), 'README.md', [
+    '# Reference Notes',
+    '',
+    'Add supporting documentation here.',
+  ]);
+  createPlaceholder(path.join(skillDir, 'assets'), 'README.md', [
+    '# Assets',
+    '',
+    'Place templates, images, or other assets here.',
+  ]);
+
+  console.log(`Skill scaffold created at ${skillDir}`);
+}
+
+if (require.main === module) {
+  main();
+}

package/skills/aipk_skill_generate/scripts/package_skill.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const USAGE = `
+Usage: node scripts/package_skill.js <skill-directory>
+
+Example:
+  node scripts/package_skill.js skills/aipk_design
+`;
+
+function parseFrontMatter(content) {
+  if (!content.startsWith('---')) return null;
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) return null;
+  const block = content.slice(3, endIndex).trim();
+  const metadata = {};
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.includes(':')) continue;
+    const [key, ...rest] = line.split(':');
+    metadata[key.trim()] = rest.join(':').trim();
+  }
+  return metadata;
+}
+
+function validateSkill(skillDir) {
+  const errors = [];
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    errors.push(`Skill directory not found: ${skillDir}`);
+    return errors;
+  }
+  const skillName = path.basename(skillDir);
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) {
+    errors.push('SKILL.md is missing');
+    return errors;
+  }
+  const content = fs.readFileSync(skillMd, 'utf8');
+  const metadata = parseFrontMatter(content);
+  if (!metadata) {
+    errors.push('SKILL.md front matter is missing or malformed');
+    return errors;
+  }
+  if (!metadata.name) {
+    errors.push('Front matter missing "name"');
+  } else if (metadata.name !== skillName) {
+    errors.push(`Front matter "name" (${metadata.name}) must match directory (${skillName})`);
+  }
+  if (!metadata.description) {
+    errors.push('Front matter missing "description"');
+  }
+  return errors;
+}
+
+function main() {
+  const [skillDir] = process.argv.slice(2);
+  if (!skillDir) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+  const resolved = path.resolve(skillDir);
+  const errors = validateSkill(resolved);
+  if (errors.length) {
+    console.error('Skill validation failed:');
+    for (const err of errors) {
+      console.error('- ' + err);
+    }
+    process.exit(1);
+  }
+  console.log(`Skill validation passed for ${resolved}`);
+}
+
+if (require.main === module) {
+  main();
+}

package/skills/aipk_tool_prompts/GURU_AI.md

@@ -1,6 +1,6 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-17T08:21:07.943Z
+Last refreshed: 2025-11-17T08:34:27.508Z
 
 | File | Last Modified (UTC) |
 | --- | --- |