@prismshadow/penguin-skills 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,32 @@
+# @prismshadow/penguin-skills
+
+The PenguinHarness built-in skill library. A Skill is a directory with a `SKILL.md` (frontmatter: name, description, version, updated) — files are the runtime source of truth and ship raw in this package's npm tarball.
+
+Skills follow the "index first, body on demand" design: only their metadata is injected into an Agent's system prompt; the Agent reads the full `SKILL.md` via shell when it actually needs it.
+
+Included skills:
+
+| Group | Skills |
+| --- | --- |
+| Agent Development | `agent-creation`, `benchmark-design`, `agent-evaluation`, `agent-optimization` |
+| Data Analysis | `data-analysis` |
+| Penguin Development | `penguin-sdk`, `penguin-cli`, `agenthub-models` |
+| Web Development | `web-design` |
+| Software Engineering | `software-engineering` |
+
+The first group powers the self-improvement loop: design a Benchmark, evaluate the Target Agent, optimize it to version N+1 with a snapshot before every round.
+
+## Documentation
+
+- [Skills](https://penguin.ooo/docs/skills)
+- [Self-Improvement](https://penguin.ooo/docs/self-improvement)
+
+## Development
+
+```bash
+pnpm --filter @prismshadow/penguin-skills build      # tsup → dist/ (loader API)
+pnpm --filter @prismshadow/penguin-skills typecheck
+pnpm --filter @prismshadow/penguin-skills test
+```
+
+Part of [PenguinHarness](https://github.com/Prism-Shadow/penguin-harness) · Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/** Skill's frontmatter metadata (four fields: name / description / version / updated; description itself is English-only, may also carry description_zh and short_description(_zh)). */
+interface SkillMetadata {
+    /** Skill name (matches its containing directory name). */
+    name: string;
+    /** One-line description; injected into the model prompt via `{{SKILL_METADATA}}`. */
+    description: string;
+    /** UI short description (frontmatter `short_description`, optional): preferred in compact spots like cards, falls back to the full description if missing; not injected into the prompt. */
+    shortDescription?: string;
+    /** Chinese short description (frontmatter `short_description_zh`, optional). */
+    shortDescriptionZh?: string;
+    /** Version number (natural number); falls back to 1 on parse failure. */
+    version: number;
+    /** Update date (YYYY-MM-DD); defaults to "". */
+    updated: string;
+}
+/** A Skill in the library: metadata + full SKILL.md content (including frontmatter, written as-is on install). */
+interface LibrarySkill extends SkillMetadata {
+    content: string;
+    /** Optional raw `icon.svg` content in the directory (custom icon, the file is the sole source, copied alongside SKILL.md on install); absent means none (frontend falls back to the default book icon). */
+    icon?: string;
+}
+/** Skill group manifest entry: group id, title (optionally with a Chinese title, displayed per UI language), and member Skill names. */
+interface SkillGroupInfo {
+    id: string;
+    title: string;
+    /** Chinese group title (optional, displayed per UI language). */
+    titleZh?: string;
+    /** Member Skill names (i.e., directory names under `skills/`). */
+    skills: string[];
+}
+/** Grouping result: group metadata + member Skills read from library files. */
+interface ResolvedSkillGroup extends Omit<SkillGroupInfo, "skills"> {
+    skills: LibrarySkill[];
+}
+/**
+ * Parses the frontmatter at the start of SKILL.md: only recognizes `key: value` lines inside the
+ * first `---` block (split on the first colon, value trimmed, values may themselves contain colons);
+ * all fields are scalars, no YAML dependency needed.
+ * Error tolerance: returns null if the `---` block or name is missing; version falls back to 1 if
+ * it isn't a natural number; updated defaults to "".
+ */
+declare function parseSkillFrontmatter(content: string): SkillMetadata | null;
+/** Reads all Skills in the library (one per subdirectory under `skills/`), sorted by name. */
+declare function loadLibrarySkills(): LibrarySkill[];
+/**
+ * Skill group manifest; members are library directory names.
+ * Docs: /docs/skills § "Built-in library".
+ */
+declare const SKILL_GROUPS: SkillGroupInfo[];
+/**
+ * Groups library Skills according to SKILL_GROUPS (a member name missing from `all` is skipped);
+ * Skills not listed in any group are appended to an Other group (only appears if non-empty). A
+ * pure function, the testable core of loadSkillGroups.
+ */
+declare function groupSkills(all: LibrarySkill[]): ResolvedSkillGroup[];
+/** Reads library files and groups them: SKILL_GROUPS order comes first, ungrouped Skills are appended to an Other group (only appears if non-empty). */
+declare function loadSkillGroups(): ResolvedSkillGroup[];
+/** Reads a single library Skill by name; returns undefined if the name contains illegal characters (path traversal guard) or doesn't exist. */
+declare function librarySkill(name: string): LibrarySkill | undefined;
+
+export { type LibrarySkill, type ResolvedSkillGroup, SKILL_GROUPS, type SkillGroupInfo, type SkillMetadata, groupSkills, librarySkill, loadLibrarySkills, loadSkillGroups, parseSkillFrontmatter };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function parseSkillFrontmatter(content) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content.replace(/^\uFEFF/, ""));
+  if (!match) return null;
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    if (key) fields[key] = line.slice(idx + 1).trim();
+  }
+  const name = fields["name"];
+  if (!name) return null;
+  const version = Number.parseInt(fields["version"] ?? "", 10);
+  const shortDescription = fields["short_description"];
+  const shortDescriptionZh = fields["short_description_zh"];
+  return {
+    name,
+    description: fields["description"] ?? "",
+    // short_description(_zh) is optional: omitted when absent (undefined keys aren't set).
+    ...shortDescription !== void 0 ? { shortDescription } : {},
+    ...shortDescriptionZh !== void 0 ? { shortDescriptionZh } : {},
+    version: Number.isInteger(version) && version >= 1 ? version : 1,
+    updated: fields["updated"] ?? ""
+  };
+}
+var SKILLS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+var SKILL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+function readSkillDir(name) {
+  const dir = path.join(SKILLS_ROOT, name);
+  let content;
+  try {
+    content = fs.readFileSync(path.join(dir, "SKILL.md"), "utf8");
+  } catch {
+    return void 0;
+  }
+  let icon;
+  try {
+    icon = fs.readFileSync(path.join(dir, "icon.svg"), "utf8");
+  } catch {
+  }
+  const meta = parseSkillFrontmatter(content) ?? {
+    name,
+    description: "",
+    version: 1,
+    updated: ""
+  };
+  return { ...meta, name, content, ...icon !== void 0 ? { icon } : {} };
+}
+function loadLibrarySkills() {
+  const skills = [];
+  for (const entry of fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skill = readSkillDir(entry.name);
+    if (skill) skills.push(skill);
+  }
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+var SKILL_GROUPS = [
+  {
+    id: "agent-development",
+    title: "Agent Development",
+    titleZh: "Agent \u5F00\u53D1",
+    skills: ["agent-creation", "benchmark-design", "agent-evaluation", "agent-optimization"]
+  },
+  {
+    id: "data-analysis",
+    title: "Data Analysis",
+    titleZh: "\u6570\u636E\u5206\u6790",
+    skills: ["data-analysis"]
+  },
+  {
+    id: "penguin-development",
+    title: "Penguin Development",
+    titleZh: "Penguin \u5F00\u53D1",
+    skills: ["penguin-sdk", "penguin-cli", "agenthub-models"]
+  },
+  {
+    id: "web-development",
+    title: "Web Development",
+    titleZh: "\u7F51\u9875\u5F00\u53D1",
+    skills: ["web-design"]
+  },
+  {
+    id: "software-engineering",
+    title: "Software Engineering",
+    titleZh: "\u8F6F\u4EF6\u5DE5\u7A0B",
+    skills: ["software-engineering"]
+  }
+];
+function groupSkills(all) {
+  const byName = new Map(all.map((skill) => [skill.name, skill]));
+  const grouped = /* @__PURE__ */ new Set();
+  const groups = SKILL_GROUPS.map((group) => {
+    const members = [];
+    for (const name of group.skills) {
+      const skill = byName.get(name);
+      if (!skill) continue;
+      members.push(skill);
+      grouped.add(name);
+    }
+    return { ...group, skills: members };
+  });
+  const others = all.filter((skill) => !grouped.has(skill.name));
+  if (others.length > 0) {
+    groups.push({
+      id: "other",
+      title: "Other",
+      titleZh: "\u5176\u4ED6",
+      skills: others
+    });
+  }
+  return groups;
+}
+function loadSkillGroups() {
+  return groupSkills(loadLibrarySkills());
+}
+function librarySkill(name) {
+  if (!SKILL_NAME_PATTERN.test(name)) return void 0;
+  return readSkillDir(name);
+}
+export {
+  SKILL_GROUPS,
+  groupSkills,
+  librarySkill,
+  loadLibrarySkills,
+  loadSkillGroups,
+  parseSkillFrontmatter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * PenguinHarness Skill library: built-in SKILL.md docs and skill group manifest.\n *\n * The runtime source of truth for library content is the package's `skills/<skill_name>/SKILL.md`\n * files: frontmatter is parsed on read (same rules as installed Skills), so editing a file takes\n * effect immediately with no caching (files are small, calls are infrequent). Only the skill group\n * manifest (id, title, and member names) is hardcoded in code; install / uninstall / scan still live\n * in core's state layer.\n *\n * Docs: packages/docs/content/skills.{zh,en}.md (site path /docs/skills) documents the Skill\n * format and the built-in library.\n */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n/** Skill's frontmatter metadata (four fields: name / description / version / updated; description itself is English-only, may also carry description_zh and short_description(_zh)). */\nexport interface SkillMetadata {\n  /** Skill name (matches its containing directory name). */\n  name: string;\n  /** One-line description; injected into the model prompt via `{{SKILL_METADATA}}`. */\n  description: string;\n  /** UI short description (frontmatter `short_description`, optional): preferred in compact spots like cards, falls back to the full description if missing; not injected into the prompt. */\n  shortDescription?: string;\n  /** Chinese short description (frontmatter `short_description_zh`, optional). */\n  shortDescriptionZh?: string;\n  /** Version number (natural number); falls back to 1 on parse failure. */\n  version: number;\n  /** Update date (YYYY-MM-DD); defaults to \"\". */\n  updated: string;\n}\n\n/** A Skill in the library: metadata + full SKILL.md content (including frontmatter, written as-is on install). */\nexport interface LibrarySkill extends SkillMetadata {\n  content: string;\n  /** Optional raw `icon.svg` content in the directory (custom icon, the file is the sole source, copied alongside SKILL.md on install); absent means none (frontend falls back to the default book icon). */\n  icon?: string;\n}\n\n/** Skill group manifest entry: group id, title (optionally with a Chinese title, displayed per UI language), and member Skill names. */\nexport interface SkillGroupInfo {\n  id: string;\n  title: string;\n  /** Chinese group title (optional, displayed per UI language). */\n  titleZh?: string;\n  /** Member Skill names (i.e., directory names under `skills/`). */\n  skills: string[];\n}\n\n/** Grouping result: group metadata + member Skills read from library files. */\nexport interface ResolvedSkillGroup extends Omit<SkillGroupInfo, \"skills\"> {\n  skills: LibrarySkill[];\n}\n\n/**\n * Parses the frontmatter at the start of SKILL.md: only recognizes `key: value` lines inside the\n * first `---` block (split on the first colon, value trimmed, values may themselves contain colons);\n * all fields are scalars, no YAML dependency needed.\n * Error tolerance: returns null if the `---` block or name is missing; version falls back to 1 if\n * it isn't a natural number; updated defaults to \"\".\n */\nexport function parseSkillFrontmatter(content: string): SkillMetadata | null {\n  // Strip a possible UTF-8 BOM (may be introduced by editors when manually editing an installed SKILL.md); CRLF is handled by \\r?\\n.\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/.exec(content.replace(/^\\uFEFF/, \"\"));\n  if (!match) return null;\n  const fields: Record<string, string> = {};\n  for (const line of match[1]!.split(/\\r?\\n/)) {\n    const idx = line.indexOf(\":\");\n    if (idx <= 0) continue;\n    const key = line.slice(0, idx).trim();\n    if (key) fields[key] = line.slice(idx + 1).trim();\n  }\n  const name = fields[\"name\"];\n  if (!name) return null;\n  const version = Number.parseInt(fields[\"version\"] ?? \"\", 10);\n  const shortDescription = fields[\"short_description\"];\n  const shortDescriptionZh = fields[\"short_description_zh\"];\n  return {\n    name,\n    description: fields[\"description\"] ?? \"\",\n    // short_description(_zh) is optional: omitted when absent (undefined keys aren't set).\n    ...(shortDescription !== undefined ? { shortDescription } : {}),\n    ...(shortDescriptionZh !== undefined ? { shortDescriptionZh } : {}),\n    version: Number.isInteger(version) && version >= 1 ? version : 1,\n    updated: fields[\"updated\"] ?? \"\",\n  };\n}\n\n/** Root directory of library files: the package's `skills/` (both dist/ and src/ sit one level below the package root, so one level up reaches it). */\nconst SKILLS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"skills\");\n\n/** Character rule for Skill names (directory names): prevents path traversal. */\nconst SKILL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;\n\n/**\n * Reads a single library directory to construct a LibrarySkill; returns undefined if SKILL.md\n * doesn't exist. name is taken from the directory name (overriding frontmatter); falls back to\n * empty metadata if frontmatter parsing fails.\n * The optional icon.svg in the directory is read alongside it (as a raw string); the icon field\n * is omitted if missing.\n */\nfunction readSkillDir(name: string): LibrarySkill | undefined {\n  const dir = path.join(SKILLS_ROOT, name);\n  let content: string;\n  try {\n    content = fs.readFileSync(path.join(dir, \"SKILL.md\"), \"utf8\");\n  } catch {\n    return undefined;\n  }\n  let icon: string | undefined;\n  try {\n    icon = fs.readFileSync(path.join(dir, \"icon.svg\"), \"utf8\");\n  } catch {\n    // icon.svg is optional: no custom icon if missing.\n  }\n  const meta = parseSkillFrontmatter(content) ?? {\n    name,\n    description: \"\",\n    version: 1,\n    updated: \"\",\n  };\n  return { ...meta, name, content, ...(icon !== undefined ? { icon } : {}) };\n}\n\n/** Reads all Skills in the library (one per subdirectory under `skills/`), sorted by name. */\nexport function loadLibrarySkills(): LibrarySkill[] {\n  const skills: LibrarySkill[] = [];\n  for (const entry of fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })) {\n    if (!entry.isDirectory()) continue;\n    const skill = readSkillDir(entry.name);\n    if (skill) skills.push(skill);\n  }\n  return skills.sort((a, b) => a.name.localeCompare(b.name));\n}\n\n/**\n * Skill group manifest; members are library directory names.\n * Docs: /docs/skills § \"Built-in library\".\n */\nexport const SKILL_GROUPS: SkillGroupInfo[] = [\n  {\n    id: \"agent-development\",\n    title: \"Agent Development\",\n    titleZh: \"Agent 开发\",\n    skills: [\"agent-creation\", \"benchmark-design\", \"agent-evaluation\", \"agent-optimization\"],\n  },\n  {\n    id: \"data-analysis\",\n    title: \"Data Analysis\",\n    titleZh: \"数据分析\",\n    skills: [\"data-analysis\"],\n  },\n  {\n    id: \"penguin-development\",\n    title: \"Penguin Development\",\n    titleZh: \"Penguin 开发\",\n    skills: [\"penguin-sdk\", \"penguin-cli\", \"agenthub-models\"],\n  },\n  {\n    id: \"web-development\",\n    title: \"Web Development\",\n    titleZh: \"网页开发\",\n    skills: [\"web-design\"],\n  },\n  {\n    id: \"software-engineering\",\n    title: \"Software Engineering\",\n    titleZh: \"软件工程\",\n    skills: [\"software-engineering\"],\n  },\n];\n\n/**\n * Groups library Skills according to SKILL_GROUPS (a member name missing from `all` is skipped);\n * Skills not listed in any group are appended to an Other group (only appears if non-empty). A\n * pure function, the testable core of loadSkillGroups.\n */\nexport function groupSkills(all: LibrarySkill[]): ResolvedSkillGroup[] {\n  const byName = new Map(all.map((skill) => [skill.name, skill]));\n  const grouped = new Set<string>();\n  const groups: ResolvedSkillGroup[] = SKILL_GROUPS.map((group) => {\n    const members: LibrarySkill[] = [];\n    for (const name of group.skills) {\n      const skill = byName.get(name);\n      if (!skill) continue;\n      members.push(skill);\n      grouped.add(name);\n    }\n    return { ...group, skills: members };\n  });\n  const others = all.filter((skill) => !grouped.has(skill.name));\n  if (others.length > 0) {\n    groups.push({\n      id: \"other\",\n      title: \"Other\",\n      titleZh: \"其他\",\n      skills: others,\n    });\n  }\n  return groups;\n}\n\n/** Reads library files and groups them: SKILL_GROUPS order comes first, ungrouped Skills are appended to an Other group (only appears if non-empty). */\nexport function loadSkillGroups(): ResolvedSkillGroup[] {\n  return groupSkills(loadLibrarySkills());\n}\n\n/** Reads a single library Skill by name; returns undefined if the name contains illegal characters (path traversal guard) or doesn't exist. */\nexport function librarySkill(name: string): LibrarySkill | undefined {\n  if (!SKILL_NAME_PATTERN.test(name)) return undefined;\n  return readSkillDir(name);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@prismshadow/penguin-skills",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "PenguinHarness skill library: built-in SKILL.md documents and skill groups, decoupled from core.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/penguin-harness.git",
+    "directory": "packages/skills"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsup"
+  }
+}

package/skills/agent-creation/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-creation
+description: Turn a user requirement into a concrete agent — write the target agent's AGENTS.md and install the skills it needs.
+short_description: Turn a requirement into a working agent.
+short_description_zh: 把需求变成可用的 Agent。
+version: 1
+updated: 2026-07-17T00:00:00Z
+---
+
+# Agent Creation
+
+This skill turns a user requirement into a working agent configuration — plain files in the target agent's directory.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use agent-creation skill") without a concrete requirement, ask the user what agent they want and what it should do. Do not start until the requirement is clear.
+
+## Locate the target agent
+
+All agents of this project live side by side in the project directory:
+
+```bash
+PROJECT_DIR="<project_dir>"        # the Project Dir value from your Environment section
+ls "$PROJECT_DIR/agents"          # existing agents (each is a folder here)
+TARGET="$PROJECT_DIR/agents/<agent_id>"   # the agent to configure
+```
+
+An agent directory contains `agent_state/` (`system_config.yaml`, `AGENTS.md`, `skills/`, `memory/`, `tools/`) plus `scratchpad/` — and `traces/`, which appears once the agent has run at least once.
+
+## Write AGENTS.md
+
+`agent_state/AGENTS.md` is injected into the agent's system prompt — it is where the user requirement becomes behavior. Keep `system_config.yaml`'s `system_prompt` untouched (that is the stable system layer); put everything requirement-specific in AGENTS.md:
+
+- Role — what the agent is for, in one or two sentences.
+- Domain guidance — the concrete rules, steps and constraints derived from the user requirement.
+
+Be concise: AGENTS.md is prompt context, not documentation.
+
+## Install skills
+
+A skill is a directory `agent_state/skills/<skill_name>/` containing a `SKILL.md`:
+
+```md
+---
+name: <skill_name>
+description: <skill_description>
+version: 1
+updated: <ISO 8601 timestamp>
+---
+
+<skill_instructions>
+```
+
+The frontmatter may also carry optional `short_description` and `short_description_zh` lines (a short UI blurb and its Chinese variant) — the UI prefers them for display, while prompt injection always uses the English `description`.
+
+Installing is all it takes: the frontmatter metadata of every `SKILL.md` under `skills/` is injected into the target agent's system prompt automatically — do not register skills in AGENTS.md.
+
+Write skills yourself, or fetch existing ones from the internet with shell commands (`curl`, `git clone`) and place them under `skills/`. Anything fetched from the internet must be read in full and reviewed before installing — a skill becomes durable instructions the target agent will follow in every future session; never install one you have not read, and tell the user what it does.
+
+## Set name and description
+
+In the target's `agent_state/system_config.yaml`, set the top-level `name:` and `description:` fields so the agent is recognizable in lists. Edit only these two fields.
+
+## Creating a brand-new agent
+
+Prefer configuring an agent the user already created. If you must create one from scratch: pick a short id (letters, digits, `_`, `-`), copy the default agent's `system_config.yaml` as the base, and create the layout described above:
+
+```bash
+mkdir -p "$TARGET/agent_state/skills" "$TARGET/agent_state/memory" "$TARGET/agent_state/tools" "$TARGET/scratchpad"
+cp "$PROJECT_DIR/agents/default_agent/agent_state/system_config.yaml" "$TARGET/agent_state/"
+```
+
+A new agent starts with no skills — install only what it needs. Then write its AGENTS.md, name and description as above.

package/skills/agent-creation/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="9.5" cy="8" r="3.3" />
+  <path d="M3.8 20c0-3.1 2.6-5.7 5.7-5.7 1.5 0 2.9.6 3.9 1.5" />
+  <path d="M18 13.5v7" />
+  <path d="M14.5 17h7" />
+</svg>