@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/docs/reference/skill-standard.md

@@ -0,0 +1,457 @@
+# Agent Skill Standard
+
+> **Official specification from [agentskills.io](https://agentskills.io)**
+>
+> Source: [github.com/agentskills/agentskills](https://github.com/agentskills/agentskills)
+
+---
+
+## 📁 Directory Structure
+
+```
+skill-name/
+├── SKILL.md          # Required - instructions + metadata
+├── scripts/          # Optional - executable code
+├── references/       # Optional - documentation
+└── assets/           # Optional - templates, resources
+```
+
+> **Note:** Both `SKILL.md` (uppercase, preferred) and `skill.md` (lowercase) are accepted.
+
+---
+
+## 📋 SKILL.md Format
+
+### File Must Start with Frontmatter
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it.
+---
+# Skill Title
+Instructions go here...
+```
+
+> ⚠️ **Critical:** File MUST start with `---` (YAML frontmatter). No content before it.
+
+### Required Fields
+
+| Field         | Required | Max Length | Constraints                              |
+| ------------- | -------- | ---------- | ---------------------------------------- |
+| `name`        | ✅ Yes   | 64 chars   | kebab-case, lowercase, matches directory |
+| `description` | ✅ Yes   | 1024 chars | Non-empty, descriptive                   |
+
+### Optional Fields
+
+| Field           | Max Length | Purpose                                      |
+| --------------- | ---------- | -------------------------------------------- |
+| `license`       | -          | License name or file reference               |
+| `compatibility` | 500 chars  | Environment requirements                     |
+| `metadata`      | -          | Key-value pairs (**values must be strings**) |
+| `allowed-tools` | -          | Space-delimited tool patterns (experimental) |
+
+### ⚠️ Only 6 Allowed Fields
+
+```yaml
+# ONLY these fields are valid:
+name, description, license, compatibility, metadata, allowed-tools
+```
+
+Any other fields will cause validation errors.
+
+### Full Example
+
+```yaml
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or forms.
+license: Apache-2.0
+compatibility: Requires Python 3.9+ and pdfplumber
+metadata:
+  author: "example-org"
+  version: "1.0"
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+---
+# PDF Processing
+
+## When to use this skill
+...
+```
+
+---
+
+## ✅ Validation Rules
+
+### `name` Field (Required)
+
+| Rule        | Constraint                    | Example                                       |
+| ----------- | ----------------------------- | --------------------------------------------- |
+| Length      | 1-64 characters               | ✅ `pdf-processing`                           |
+| Case        | **Lowercase only**            | ❌ `PDF-Processing`                           |
+| Characters  | Unicode letters, numbers, `-` | ❌ `pdf_processing` (underscore invalid)      |
+| Start/End   | Cannot start/end with `-`     | ❌ `-pdf`, `pdf-`                             |
+| Consecutive | No `--`                       | ❌ `pdf--processing`                          |
+| Match       | Must match directory name     | ✅ `pdf-processing/` → `name: pdf-processing` |
+
+#### i18n Support
+
+Skill names support **internationalization** with Unicode characters:
+
+```yaml
+# ✅ Valid - Chinese characters
+name: 技能
+name: 处理工具
+
+# ✅ Valid - Russian characters
+name: навык
+name: мой-навык
+
+# ✅ Valid - Accented characters
+name: café-processor
+
+# ❌ Invalid - uppercase not allowed (any language)
+name: НАВЫК  # Russian uppercase
+name: 技能大写  # Must be lowercase equivalent
+```
+
+> **Note:** Names are **NFKC normalized** before validation. This means `café` (precomposed) and `cafe\u0301` (decomposed with combining accent) are treated as identical.
+
+### `description` Field (Required)
+
+| Rule     | Constraint                                  |
+| -------- | ------------------------------------------- |
+| Length   | 1-1024 characters                           |
+| Content  | Non-empty, descriptive                      |
+| Purpose  | Describe WHAT it does AND WHEN to use it    |
+| Keywords | Include task-relevant keywords for matching |
+
+✅ **Good:**
+
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+```
+
+❌ **Poor:**
+
+```yaml
+description: Helps with PDFs.
+```
+
+### `metadata` Field (Optional)
+
+| Rule   | Constraint                           |
+| ------ | ------------------------------------ |
+| Type   | Dictionary (key-value pairs)         |
+| Keys   | Must be strings                      |
+| Values | **Must be strings** (quote numbers!) |
+
+```yaml
+# ✅ Correct - values are strings
+metadata:
+  author: "example-org"
+  version: "1.0"
+
+# ❌ Wrong - number without quotes
+metadata:
+  version: 1.0
+```
+
+---
+
+## 📏 Size Limits
+
+| Element                     | Limit           | Tokens           |
+| --------------------------- | --------------- | ---------------- |
+| Metadata (name+description) | -               | ~50-100 tokens   |
+| Main SKILL.md               | **< 500 lines** | < 5000 tokens    |
+| Reference files             | As needed       | Loaded on demand |
+
+---
+
+## 📂 Optional Directories
+
+### scripts/
+
+Executable code agents can run:
+
+- Self-contained or document dependencies
+- Include helpful error messages
+- Handle edge cases gracefully
+- Supported: Python, Bash, JavaScript
+
+### references/
+
+Additional documentation loaded on demand:
+
+- `REFERENCE.md` - Detailed technical docs
+- `FORMS.md` - Templates or structured data
+- Domain-specific files (`finance.md`, `legal.md`)
+
+### assets/
+
+Static resources:
+
+- Templates (document, config)
+- Images (diagrams, examples)
+- Data files (schemas, lookup tables)
+
+---
+
+## 🔄 Progressive Disclosure
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. DISCOVERY (~50-100 tokens per skill)                 │
+│    Only name + description loaded at startup            │
+├─────────────────────────────────────────────────────────┤
+│ 2. ACTIVATION (< 5000 tokens)                           │
+│    Full SKILL.md loaded when task matches description   │
+├─────────────────────────────────────────────────────────┤
+│ 3. EXECUTION (as needed)                                │
+│    scripts/, references/, assets/ loaded on demand      │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔗 File References
+
+Use relative paths from skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Keep references **one level deep**. Avoid deeply nested chains.
+
+---
+
+## 🛡️ Security Guidelines
+
+When executing scripts:
+
+| Guideline        | Description                               |
+| ---------------- | ----------------------------------------- |
+| **Sandboxing**   | Run scripts in isolated environments      |
+| **Allowlisting** | Only execute scripts from trusted skills  |
+| **Confirmation** | Ask users before dangerous operations     |
+| **Logging**      | Record all script executions for auditing |
+
+---
+
+## 📡 XML Format for Agent Prompts
+
+When injecting skills into agent system prompts, use XML format:
+
+```xml
+<available_skills>
+<skill>
+<name>pdf-processing</name>
+<description>Extract text and tables from PDF files, fill forms, merge documents.</description>
+<location>/path/to/skills/pdf-processing/SKILL.md</location>
+</skill>
+<skill>
+<name>data-analysis</name>
+<description>Analyzes datasets, generates charts, and creates summary reports.</description>
+<location>/path/to/skills/data-analysis/SKILL.md</location>
+</skill>
+</available_skills>
+```
+
+---
+
+## 🧪 Validation
+
+### Using skills-ref (Official Python Library)
+
+```bash
+# Install
+pip install skills-ref
+```
+
+#### CLI Commands
+
+| Command                                   | Purpose                           | Exit Code              |
+| ----------------------------------------- | --------------------------------- | ---------------------- |
+| `skills-ref validate <path>`              | Validate SKILL.md format          | 0 = valid, 1 = errors  |
+| `skills-ref read-properties <path>`       | Parse frontmatter to JSON         | 0 = success, 1 = error |
+| `skills-ref to-prompt <path1> <path2>...` | Generate `<available_skills>` XML | 0 = success, 1 = error |
+
+**Examples:**
+
+```bash
+# Validate a skill
+skills-ref validate ./my-skill
+# Output: Valid skill: ./my-skill
+
+# Read properties as JSON
+skills-ref read-properties ./my-skill
+# Output: {"name": "my-skill", "description": "..."}
+
+# Generate XML for multiple skills
+skills-ref to-prompt ./skill1 ./skill2 ./skill3
+# Output: <available_skills>...</available_skills>
+```
+
+> **Tip:** You can pass a SKILL.md file path directly; the tool will use its parent directory.
+
+---
+
+## 📊 Compliance Checklist
+
+| #   | Check | Requirement                                                |
+| --- | ----- | ---------------------------------------------------------- |
+| 1   | ☐     | `SKILL.md` or `skill.md` exists in directory               |
+| 2   | ☐     | File starts with `---` (YAML frontmatter)                  |
+| 3   | ☐     | `name` field present and non-empty                         |
+| 4   | ☐     | `name` is lowercase (any Unicode script)                   |
+| 5   | ☐     | `name` is 1-64 characters                                  |
+| 6   | ☐     | `name` matches directory name exactly (NFKC normalized)    |
+| 7   | ☐     | No underscores (`_`) or consecutive hyphens (`--`) in name |
+| 8   | ☐     | `description` field present, 1-1024 chars                  |
+| 9   | ☐     | Only 6 allowed frontmatter fields used                     |
+| 10  | ☐     | `metadata` values are strings (quoted)                     |
+| 11  | ☐     | `compatibility` field < 500 chars (if present)             |
+| 12  | ☐     | SKILL.md < 500 lines recommended                           |
+
+---
+
+## 📚 Reference
+
+| Resource               | URL                                                                                                                        |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Official Specification | [agentskills.io/specification](https://agentskills.io/specification)                                                       |
+| Example Skills         | [github.com/anthropics/skills](https://github.com/anthropics/skills)                                                       |
+| Reference Library      | [github.com/agentskills/agentskills/skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref)           |
+| Best Practices         | [platform.claude.com/.../best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) |
+| Vercel Labs Examples   | [github.com/vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)                                         |
+
+---
+
+## 🏆 Best Practices (from Vercel Labs)
+
+> Patterns from production-grade skill implementations at Vercel.
+
+### 1. Trigger Phrases in Description
+
+Include explicit trigger phrases to improve agent matching:
+
+```yaml
+# ✅ Excellent - includes trigger phrases
+description: >
+  React and Next.js performance optimization guidelines.
+  Triggers on tasks involving React components, Next.js pages,
+  data fetching, bundle optimization, or performance improvements.
+
+# ❌ Weak - no trigger phrases
+description: React best practices guide.
+```
+
+### 2. Rule File Organization
+
+For large skills (>300 lines), split into individual rule files:
+
+```
+skill-name/
+├── SKILL.md            # Index (~100-150 lines)
+├── AGENTS.md           # Compiled full version (optional)
+├── rules/
+│   ├── _template.md    # Rule template for consistency
+│   ├── _sections.md    # Section definitions
+│   ├── async-parallel.md
+│   ├── bundle-imports.md
+│   └── server-cache.md
+```
+
+### 3. Priority Prefix System
+
+Use prefixes to categorize rules by impact:
+
+| Prefix      | Impact      | Example                |
+| ----------- | ----------- | ---------------------- |
+| `async-`    | CRITICAL    | `async-parallel.md`    |
+| `bundle-`   | CRITICAL    | `bundle-imports.md`    |
+| `server-`   | HIGH        | `server-cache.md`      |
+| `client-`   | MEDIUM-HIGH | `client-dedup.md`      |
+| `rerender-` | MEDIUM      | `rerender-memo.md`     |
+| `js-`       | LOW-MEDIUM  | `js-early-exit.md`     |
+| `advanced-` | LOW         | `advanced-patterns.md` |
+
+### 4. Rule File Template
+
+Each rule file should follow this format:
+
+````yaml
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: 20-50% improvement
+tags: async, performance
+---
+## Rule Title Here
+
+Brief explanation of why this matters.
+
+**Incorrect (what's wrong):**
+
+```typescript
+// Bad code
+````
+
+**Correct (what's right):**
+
+```typescript
+// Good code
+```
+
+Reference: [Link to docs](https://example.com)
+
+```
+
+### 5. AGENTS.md Pattern
+
+For skills with many rules, provide a compiled `AGENTS.md`:
+
+- Contains ALL rules expanded inline
+- Used by agents that prefer single-file context
+- Auto-generated from individual rule files
+
+```
+
+skill-name/
+├── SKILL.md # Index with Quick Reference
+├── AGENTS.md # Full compiled version (~3000 lines)
+└── rules/ # Individual rule files
+
+```
+
+### 6. Context Efficiency Guidelines
+
+From Vercel's AGENTS.md:
+
+| Guideline                        | Recommendation              |
+| -------------------------------- | --------------------------- |
+| Keep SKILL.md under 500 lines    | Put details in rule files   |
+| Write specific descriptions      | Helps agent matching        |
+| Use progressive disclosure       | Reference files on-demand   |
+| Prefer scripts over inline code  | Script output only in context |
+| File references one level deep   | Avoid nested reference chains |
+
+---
+
+## 📐 Metrics Summary
+
+| Metric                    | Limit/Target          |
+| ------------------------- | --------------------- |
+| `name` length             | 1-64 chars            |
+| `description` length      | 1-1024 chars          |
+| `compatibility` length    | ≤500 chars            |
+| Discovery tokens          | ~50-100 per skill     |
+| SKILL.md lines            | <500 (recommend <150) |
+| Rule file lines           | ~30-50 each           |
+| Allowed frontmatter fields| 6 only                |
+```

package/package.json

@@ -1,22 +1,55 @@
 {
   "name": "@agentskillkit/agent-skills",
-  "version": "1.0.1",
-  "description": "The Premium Agent Skills Kit for Enterprise",
+  "version": "3.2.1",
+  "description": "The Agent Skills Kit for Enterprise",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agentskillkit/agent-skills.git"
   },
   "homepage": "https://github.com/agentskillkit/agent-skills",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    ".agent",
+    "docs",
+    "packages",
+    "scripts",
+    "tests",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "bin": {
     "agent-skills-kit": "./packages/cli/bin/ag-smart.js",
     "ag-smart": "./packages/cli/bin/ag-smart.js"
   },
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "checklist": "python .agent/scripts/checklist.py .",
+    "test": "node packages/cli/tests/integration/signal-detector.test.js",
+    "test:integration": "node packages/cli/tests/integration/gemini-export.test.js",
+    "test:scripts": "vitest run tests/scripts",
+    "example:violations": "node packages/cli/examples/demo-violations.js",
+    "rebrand": "node scripts/rebrand/index.mjs",
+    "checklist": "node .agent/scripts-js/checklist.js .",
+    "verify": "node .agent/scripts-js/verify_all.js . --url",
+    "preview:start": "node .agent/scripts-js/auto_preview.js start",
+    "preview:stop": "node .agent/scripts-js/auto_preview.js stop",
+    "preview:status": "node .agent/scripts-js/auto_preview.js status",
+    "session:status": "node .agent/scripts-js/session_manager.js status .",
+    "session:info": "node .agent/scripts-js/session_manager.js info .",
+    "studio:search": "node .agent/skills/studio/scripts-js/search.js",
+    "studio:design": "node .agent/skills/studio/scripts-js/search.js --design-system",
+    "test:studio": "vitest run tests/scripts/css-templates.test.js tests/scripts/component-specs.test.js tests/scripts/format-master-md.test.js tests/scripts/page-type-detector.test.js tests/scripts/intelligent-overrides.test.js tests/scripts/page-override-formatter.test.js tests/scripts/css-validator.test.js tests/scripts/search-cache.test.js tests/scripts/config-loader.test.js tests/scripts/integration/studio-integration.test.js",
+    "test:unit": "vitest run tests/scripts --exclude tests/scripts/integration/*",
+    "test:all": "npm run test && npm run test:integration && npm run test:studio",
     "scan:security": "python .agent/skills/vulnerability-scanner/scripts/security_scan.py .",
     "lint": "python .agent/skills/lint-and-validate/scripts/lint_runner.py .",
-    "learn": "node packages/cli/lib/learn.js"
+    "learn": "node packages/cli/lib/learn.js",
+    "workflow:validate": "node .agent/scripts-js/workflow-validator.js",
+    "workflow:list": "node .agent/scripts-js/workflow-engine.js --list",
+    "workflow:run": "node .agent/scripts-js/workflow-engine.js",
+    "agent": "agent"
   },
   "keywords": [
     "ai",
@@ -29,10 +62,21 @@
   "author": "agentskillkit <agentskillkit@gmail.com>",
   "license": "UNLICENSED",
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "agentskillskit-cli": "file:packages/cli",
     "eslint": "^9.0.0",
-    "prettier": "^3.0.0"
+    "gray-matter": "^4.0.3",
+    "prettier": "^3.0.0",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
-    "js-yaml": "^4.1.1"
+    "@clack/prompts": "^0.11.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "css-tree": "^3.1.0",
+    "csv-parse": "^6.1.0",
+    "glob": "^13.0.0",
+    "js-yaml": "^4.1.1",
+    "picocolors": "^1.1.1"
   }
 }

package/packages/cli/.agent/knowledge/evolution-signals.json

@@ -0,0 +1,51 @@
+{
+  "signals": [
+    {
+      "id": "signal_1738148400000_console_log",
+      "lessonId": "LEARN-002",
+      "reason": "hitCountThreshold",
+      "confidence": 0.95,
+      "status": "pending",
+      "metadata": {
+        "triggerEvent": "violation",
+        "file": "lib/ui/lessons-ui.js",
+        "matchCount": 16,
+        "timestamp": 1738148400000
+      },
+      "createdAt": 1738148400000,
+      "resolvedAt": null
+    },
+    {
+      "id": "signal_1738148400000_todo_comments",
+      "lessonId": "LEARN-001",
+      "reason": "hitCountThreshold",
+      "confidence": 0.9,
+      "status": "pending",
+      "metadata": {
+        "triggerEvent": "violation",
+        "file": "lib/knowledge-validator.js",
+        "matchCount": 3,
+        "timestamp": 1738148400000
+      },
+      "createdAt": 1738148400000,
+      "resolvedAt": null
+    },
+    {
+      "id": "signal_1738148400000_var_usage",
+      "lessonId": "LEARN-003",
+      "reason": "autoEscalation",
+      "confidence": 0.85,
+      "status": "resolved",
+      "metadata": {
+        "triggerEvent": "violation",
+        "file": "tests/integration/signal-detector.test.js",
+        "matchCount": 2,
+        "timestamp": 1738148400000,
+        "resolution": "Pattern refactored to use const"
+      },
+      "createdAt": 1738148400000,
+      "resolvedAt": 1738148500000
+    }
+  ],
+  "version": 1
+}

package/packages/cli/.agent/knowledge/lessons-learned.yaml

@@ -1,32 +1,42 @@
 lessons:
   - id: LEARN-001
     pattern: TODO
-    message: Please
+    message: Remove TODO comments before committing
     severity: WARNING
     category: code-quality
     source: manual
-    hitCount: 0
-    lastHit: null
-    autoEscalated: false
-    addedAt: '2026-01-24T20:54:57.262Z'
+    hitCount: 24
+    lastHit: "2026-01-29T00:00:00.000Z"
+    autoEscalated: true
+    addedAt: "2026-01-24T20:54:57.262Z"
   - id: LEARN-002
     pattern: console.log
-    message: 'No'
-    severity: ERROR
-    category: general
+    message: Remove debug console.log statements before production
+    severity: WARNING
+    category: debugging
     source: manual
-    hitCount: 20
-    lastHit: '2026-01-24T21:02:58.265Z'
+    hitCount: 1235
+    lastHit: "2026-01-29T00:00:00.000Z"
     autoEscalated: false
-    addedAt: '2026-01-24T20:59:54.591Z'
+    addedAt: "2026-01-24T20:59:54.591Z"
   - id: LEARN-003
     pattern: var\s+
-    message: Use
-    severity: WARNING
-    category: general
+    message: Use let or const instead of var (ES6+)
+    severity: ERROR
+    category: modern-syntax
+    source: manual
+    hitCount: 12
+    lastHit: "2026-01-29T00:00:00.000Z"
+    autoEscalated: true
+    addedAt: "2026-01-24T21:17:40.051Z"
+  - id: LEARN-004
+    pattern: \.then\(
+    message: Consider using async/await instead of .then() for better readability
+    severity: INFO
+    category: modern-syntax
     source: manual
     hitCount: 0
     lastHit: null
     autoEscalated: false
-    addedAt: '2026-01-24T21:17:40.051Z'
+    addedAt: "2026-01-29T00:00:00.000Z"
 version: 1