@hasna/skills 0.1.42 → 0.1.44

package/dist/lib/cli-mcp-parity.d.ts

@@ -0,0 +1,14 @@
+export type SkillsCliMcpParityDomain = "discovery" | "portable-skills" | "runtime" | "validation";
+export interface SkillsCliMcpParityEntry {
+    domain: SkillsCliMcpParityDomain;
+    operation: string;
+    cliCommands: string[];
+    mcpTools: string[];
+    jsonContracts: string[];
+    status: "matched" | "intentional-gap";
+    notes?: string;
+}
+export declare const SKILLS_CLI_MCP_PARITY: SkillsCliMcpParityEntry[];
+export declare function validateSkillsCliMcpParity(): string[];
+export declare function findSkillsParityForCliCommand(command: string): SkillsCliMcpParityEntry | undefined;
+export declare function findSkillsParityForMcpTool(tool: string): SkillsCliMcpParityEntry | undefined;

package/dist/lib/mcp-contracts.d.ts

@@ -15,7 +15,7 @@ export interface JsonSchemaObject {
     additionalProperties?: boolean | JsonSchemaObject;
     oneOf?: JsonSchemaObject[];
 }
-export type McpToolCategory = "agent-session" | "discovery" | "execution" | "feedback" | "metadata" | "pinning" | "scheduling" | "validation";
+export type McpToolCategory = "agent-session" | "discovery" | "execution" | "feedback" | "metadata" | "pinning" | "scaffolding" | "scheduling" | "validation";
 export type McpToolSideEffect = "filesystem" | "local-process-or-remote-run" | "none" | "schedule-state";
 export interface McpToolContract {
     name: string;

package/dist/lib/portable-skills.d.ts

@@ -0,0 +1,79 @@
+import type { SkillMeta } from "./registry-types.js";
+import { type SkillValidationResult } from "./skill-validation.js";
+export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
+export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
+export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+export interface PortableSkillInput {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+export interface PortableSkillCommand {
+    name: string;
+    description?: string;
+    entry?: string;
+    command?: string;
+    args?: string[];
+}
+export interface PortableSkillManifest {
+    $schema?: string;
+    standard: typeof PORTABLE_SKILL_STANDARD | string;
+    name: string;
+    description: string;
+    version: string;
+    displayName?: string;
+    category?: string;
+    tags?: string[];
+    inputs: PortableSkillInput[];
+    commands: PortableSkillCommand[];
+}
+export interface PortableSkillSummary {
+    name: string;
+    displayName: string;
+    description: string;
+    version: string;
+    path: string;
+    commands: PortableSkillCommand[];
+    source: "custom";
+    standard: string;
+}
+export interface PortableSkillOptions {
+    rootDir?: string;
+    homeDir?: string;
+}
+export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
+    description?: string;
+    overwrite?: boolean;
+}
+export interface PortPortableSkillOptions extends PortableSkillOptions {
+    name?: string;
+    overwrite?: boolean;
+}
+export interface PortableSkillWriteResult {
+    name: string;
+    path: string;
+    manifest: PortableSkillManifest;
+    created: boolean;
+}
+export interface PortableSkillRunOptions extends PortableSkillOptions {
+    stdio?: "inherit" | "pipe";
+    env?: Record<string, string>;
+}
+export interface PortableSkillRunResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+}
+export declare function normalizePortableSkillName(name: string): string;
+export declare function getPortableSkillsRoot(options?: PortableSkillOptions): string;
+export declare function getPortableSkillPath(name: string, options?: PortableSkillOptions): string;
+export declare function findPortableSkill(name: string, options?: PortableSkillOptions): PortableSkillSummary | null;
+export declare function listPortableSkills(options?: PortableSkillOptions): PortableSkillSummary[];
+export declare function listPortableSkillMetas(options?: PortableSkillOptions): SkillMeta[];
+export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
+export declare function scaffoldPortableSkill(name: string, options?: ScaffoldPortableSkillOptions): PortableSkillWriteResult;
+export declare function portPortableSkill(sourcePath: string, options?: PortPortableSkillOptions): PortableSkillWriteResult;
+export declare function validatePortableSkillDirectory(name: string, skillPath: string): SkillValidationResult;
+export declare function runPortableSkill(name: string, args: string[], options?: PortableSkillRunOptions): Promise<PortableSkillRunResult>;

package/dist/lib/registry.d.ts

@@ -8,7 +8,7 @@ export type { Category, SkillMeta, SkillRegistryProfile };
 export declare function isBasicSkillName(name: string): boolean;
 /**
  * Load the full registry: official skills merged with global custom skills
- * from ~/.hasna/skills/custom/.
+ * from ~/.hasna/skills/<name>/ and the legacy ~/.hasna/skills/custom/<name>/ path.
  *
  * Custom skills with the same name as official skills take precedence.
  * Results are cached for 5 seconds.

package/dist/lib/skill-validation.d.ts

@@ -1,4 +1,5 @@
 import type { SkillMeta } from "./registry.js";
+import type { PortableSkillManifest } from "./portable-skills.js";
 export interface SkillValidationMessage {
     code: string;
     message: string;
@@ -15,6 +16,7 @@ export interface SkillValidationResult {
         binCommands: string[];
         docFiles: string[];
         skillMdFrontmatter?: SkillFrontmatter;
+        portableManifest?: PortableSkillManifest;
         provenance?: SkillValidationProvenance;
         runtime?: "local" | "hosted";
     };

package/docs/skill-standard.md

@@ -0,0 +1,126 @@
+# Portable Skill Standard
+
+Portable skills live in one folder each:
+
+```text
+~/.hasna/skills/<skill-name>/
+├── SKILL.md
+├── skill.json
+├── AGENTS.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+```
+
+`skills new <name>` creates this layout. `skills scaffold <name>` is an alias.
+`skills port <path>` and `skills add <path>` copy an existing skill folder into
+this layout and add missing standard files.
+
+## Naming
+
+Skill names are lowercase slugs: letters, numbers, dots, underscores, and
+hyphens. The folder name, `SKILL.md` frontmatter `name`, `skill.json` `name`,
+and `package.json` `name` should match.
+
+## Manifest
+
+Every portable skill needs a manifest. `skill.json` is the machine-readable
+manifest. `SKILL.md` frontmatter stays compatible with existing Codewith
+`SKILL.md` conventions and can be used by agents for skill discovery.
+
+Minimum `SKILL.md` frontmatter:
+
+```yaml
+---
+name: my-skill
+description: What this skill does and when to use it.
+version: 0.1.0
+source: custom
+category: Development Tools
+tags:
+  - custom
+---
+```
+
+Minimum `skill.json`:
+
+```json
+{
+  "$schema": "https://hasna.dev/schemas/skill.v1.json",
+  "standard": "hasna.skill.v1",
+  "name": "my-skill",
+  "description": "What this skill does and when to use it.",
+  "version": "0.1.0",
+  "inputs": [
+    {
+      "name": "args",
+      "type": "string[]",
+      "required": false,
+      "description": "Arguments passed after `skills run my-skill`."
+    }
+  ],
+  "commands": [
+    {
+      "name": "my-skill",
+      "entry": "src/index.ts",
+      "description": "Run my-skill.",
+      "args": ["...args"]
+    }
+  ]
+}
+```
+
+If `skill.json` is absent, the CLI can infer a portable manifest from
+`SKILL.md` frontmatter plus `package.json` `bin`, but scaffolded and ported
+skills should keep `skill.json` checked in.
+
+## Agent Handoff
+
+`AGENTS.md` is required for portable skills created or ported by the CLI. It
+tells a coding agent where to put logic, how to update the manifest, how to test
+the skill, and how to verify it with:
+
+```bash
+skills validate my-skill
+skills run my-skill --help
+```
+
+## Runtime
+
+The first command in `skill.json.commands` is the default for:
+
+```bash
+skills run my-skill [args...]
+```
+
+For Bun/TypeScript skills, point `entry` at `src/index.ts`. The CLI runs the
+entry from the skill folder, passes through arguments, and records run metadata
+under the caller project’s `.skills/runs` and `.skills/exports` directories.
+
+## Validation
+
+```bash
+skills validate my-skill --json
+```
+
+Validation checks:
+
+- folder and name safety;
+- `SKILL.md` frontmatter compatibility;
+- `skill.json` standard, version, inputs, and commands;
+- `AGENTS.md` presence;
+- `package.json` and command entrypoint safety;
+- no reserved files such as `.env` or symlinks.
+
+## Porting Existing Skills
+
+```bash
+skills port ./old-skill
+skills add ./old-skill --name new-name
+```
+
+Porting copies the folder into `~/.hasna/skills/<name>/`, skips generated and
+dependency directories such as `node_modules`, `dist`, and `.git`, then adds or
+normalizes `skill.json`, `AGENTS.md`, `package.json`, `tsconfig.json`, and an
+entrypoint when they are missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "!dist/platform",
     "!dist/server",
     "bin/",
+    "docs/skill-standard.md",
     "skills/",
     "!skills/**/node_modules",
     "!skills/scaffold-project/my-app",
@@ -63,7 +64,6 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@hasna/events": "^0.1.3",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",

package/skills/apidocs/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "CLAUDE_CODE_TASK_LIST_ID": "service-apidocs-dev"
+  }
+}