@hasna/skills 0.1.43 → 0.1.45

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.43",
+  "version": "0.1.45",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -11,6 +11,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage.js",
+      "types": "./dist/storage.d.ts"
     }
   },
   "files": [
@@ -19,6 +23,7 @@
     "!dist/platform",
     "!dist/server",
     "bin/",
+    "docs/skill-standard.md",
     "skills/",
     "!skills/**/node_modules",
     "!skills/scaffold-project/my-app",
@@ -30,7 +35,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf bin/ dist/",
-    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external ink --external react --external chalk && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/index.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "test": "bun test",
     "dev": "bun run ./src/cli/index.tsx",
     "dev:watch": "bun --watch run ./src/cli/index.tsx",
@@ -60,10 +65,11 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/react": "^18.2.0",
+    "react-devtools-core": "^7.0.1",
     "typescript": "^5"
   },
   "dependencies": {
-    "@hasna/events": "^0.1.7",
+    "@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"
+  }
+}