@pikku/skills 0.12.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @pikku/skills
+
+The Pikku agent skills — the instruction set coding agents read to build, wire and
+deploy Pikku projects. **MIT licensed**, deliberately: the format and the skills are
+the open core, so any harness can adopt them without taking on the Pikku CLI's
+Business Source License.
+
+Each directory under `skills/` is one skill: a `SKILL.md` with YAML frontmatter
+(`name`, `description`, optional `installGroups`) plus any `references/` it needs.
+The frontmatter shape is the one Claude Code, opencode and pi.dev all parse.
+
+## Installing them
+
+You do not normally depend on this package directly — the CLI installs from it:
+
+```bash
+npx pikku skills install                  # → .claude/skills/
+npx pikku skills install --core --fabric  # the Fabric sandbox skill set
+npx pikku skills install --agent pi       # → .pi/skills/
+```
+
+## Reading them programmatically
+
+```ts
+import { listSkillNames, listSkillFiles, readSkillFile } from '@pikku/skills'
+
+for (const name of await listSkillNames()) {
+  for (const path of await listSkillFiles(name)) {
+    console.log(path, (await readSkillFile(path))?.length)
+  }
+}
+```
+
+Reads prefer the `skills/` directory on disk, so editing a `SKILL.md` is live
+immediately. `SKILL_FILES` is the same content as an embedded path → contents map,
+which is what makes the skills available inside the `bun --compile` CLI binaries
+where no filesystem copy exists. Regenerate it with `yarn embed` after changing
+anything under `skills/`.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { SKILL_FILES } from './skills.gen.js';
+export { SKILL_FILES };
+/**
+ * Absolute path to the `skills/` directory shipped beside this module, or `null`
+ * when there is no filesystem copy to read.
+ *
+ * Both `dist/` (published, and `src/` under tsx) sit one level below the package
+ * root, so the directory is always `../skills` when a real filesystem is in play.
+ * It is `null` inside the `bun --compile` CLI binaries, whose modules load from a
+ * virtual path — that is the case `SKILL_FILES` exists to cover.
+ */
+export declare const skillsDir: string | null;
+/**
+ * Reading prefers the filesystem so that editing a SKILL.md is immediately live
+ * for `pikku skills install` without re-running `yarn embed`; the manifest is the
+ * fallback for bundled contexts. The two are identical after a build.
+ */
+export declare const listSkillNames: () => Promise<string[]>;
+/** Every file belonging to one skill, as paths relative to the skills root. */
+export declare const listSkillFiles: (name: string) => Promise<string[]>;
+/** Contents of one file, by its path relative to the skills root. */
+export declare const readSkillFile: (path: string) => Promise<string | null>;

package/dist/index.js

@@ -0,0 +1,74 @@
+import { existsSync } from 'fs';
+import { readdir, readFile } from 'fs/promises';
+import { dirname, join, relative, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { SKILL_FILES } from './skills.gen.js';
+export { SKILL_FILES };
+/**
+ * Absolute path to the `skills/` directory shipped beside this module, or `null`
+ * when there is no filesystem copy to read.
+ *
+ * Both `dist/` (published, and `src/` under tsx) sit one level below the package
+ * root, so the directory is always `../skills` when a real filesystem is in play.
+ * It is `null` inside the `bun --compile` CLI binaries, whose modules load from a
+ * virtual path — that is the case `SKILL_FILES` exists to cover.
+ */
+export const skillsDir = (() => {
+    const candidate = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    return existsSync(candidate) ? candidate : null;
+})();
+const toPosix = (path) => path.split(sep).join('/');
+/**
+ * Reading prefers the filesystem so that editing a SKILL.md is immediately live
+ * for `pikku skills install` without re-running `yarn embed`; the manifest is the
+ * fallback for bundled contexts. The two are identical after a build.
+ */
+export const listSkillNames = async () => {
+    if (skillsDir) {
+        const entries = await readdir(skillsDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    const names = new Set();
+    for (const path of Object.keys(SKILL_FILES)) {
+        const name = path.split('/')[0];
+        if (name)
+            names.add(name);
+    }
+    return [...names].sort();
+};
+/** Every file belonging to one skill, as paths relative to the skills root. */
+export const listSkillFiles = async (name) => {
+    if (skillsDir) {
+        const root = join(skillsDir, name);
+        if (!existsSync(root))
+            return [];
+        const out = [];
+        const walk = async (dir) => {
+            for (const entry of await readdir(dir, { withFileTypes: true })) {
+                const full = join(dir, entry.name);
+                if (entry.isDirectory())
+                    await walk(full);
+                else if (entry.isFile())
+                    out.push(toPosix(relative(skillsDir, full)));
+            }
+        };
+        await walk(root);
+        return out.sort();
+    }
+    return Object.keys(SKILL_FILES)
+        .filter((path) => path.startsWith(`${name}/`))
+        .sort();
+};
+/** Contents of one file, by its path relative to the skills root. */
+export const readSkillFile = async (path) => {
+    if (skillsDir) {
+        const full = join(skillsDir, ...path.split('/'));
+        if (!existsSync(full))
+            return null;
+        return readFile(full, 'utf-8');
+    }
+    return SKILL_FILES[path] ?? null;
+};

package/dist/skills.gen.d.ts

@@ -0,0 +1 @@
+export declare const SKILL_FILES: Record<string, string>;