@matimo/core 0.1.0-alpha.9 → 0.1.0

package/dist/policy/policy-loader.js

@@ -0,0 +1,156 @@
+/**
+ * Policy-as-YAML loader for Matimo.
+ *
+ * Allows the developer to configure the policy engine through a YAML file
+ * instead of inline TypeScript, making it easy to adjust policy across
+ * environments without rebuilding.
+ *
+ * Schema for policy.yaml:
+ *
+ * ```yaml
+ * allowedDomains:
+ *   - api.slack.com
+ *   - slack.com
+ *
+ * allowedCredentials:
+ *   - SLACK_BOT_TOKEN
+ *   - OPENAI_API_KEY
+ *
+ * allowedHttpMethods:
+ *   - GET
+ *   - POST
+ *
+ * allowCommandTools: false
+ * allowFunctionTools: false
+ *
+ * protectedNamespaces:
+ *   - matimo_
+ * ```
+ *
+ * Usage:
+ *   const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ */
+import fs from 'fs';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { DefaultPolicyEngine } from './default-policy';
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+// ──────────────────────────────────────────────────────────────────────────────
+// Zod schema — validates the YAML before constructing PolicyConfig
+// ──────────────────────────────────────────────────────────────────────────────
+// Valid HTTP methods supported by the policy engine
+const VALID_HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const ValidHttpMethodEnum = z.enum(VALID_HTTP_METHODS);
+const PolicyFileSchema = z.object({
+    allowedDomains: z.array(z.string()).optional(),
+    allowedCredentials: z.array(z.string()).optional(),
+    allowedHttpMethods: z
+        .array(z
+        .string()
+        .transform((val) => val.toUpperCase())
+        .pipe(ValidHttpMethodEnum))
+        .optional(),
+    allowCommandTools: z.boolean().optional(),
+    allowFunctionTools: z.boolean().optional(),
+    protectedNamespaces: z.array(z.string()).optional(),
+    enableHITL: z.boolean().optional(),
+    quarantineRiskLevels: z.array(z.enum(['low', 'medium', 'high', 'critical'])).optional(),
+    approvalTtlSeconds: z.number().int().positive().optional(),
+});
+// ──────────────────────────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse a YAML policy file and return a PolicyEngine configured from it.
+ *
+ * Throws `MatimoError(INVALID_SCHEMA)` if the file cannot be read or fails validation.
+ *
+ * @param filePath - Absolute or cwd-relative path to the policy YAML file
+ * @returns A frozen `DefaultPolicyEngine` built from the parsed config
+ *
+ * @example
+ * ```ts
+ * // Direct usage
+ * const engine = loadPolicyFromFile('./policy.yaml');
+ * const matimo = await MatimoInstance.init({ policy: engine });
+ *
+ * // Or use the shorthand InitOption (preferred)
+ * const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ * ```
+ */
+export function loadPolicyFromFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new MatimoError(`Cannot read policy file "${filePath}": ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new MatimoError(`Policy file "${filePath}" contains invalid YAML: ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    const result = PolicyFileSchema.safeParse(parsed ?? {});
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new MatimoError(`Policy file "${filePath}" is invalid:\n${issues}`, ErrorCode.INVALID_SCHEMA, { filePath, issues: result.error.issues });
+    }
+    const policyConfig = buildPolicyConfig(result.data);
+    return new DefaultPolicyEngine(policyConfig);
+}
+/**
+ * Parse a YAML policy file into a PolicyConfig (without creating an engine).
+ * Useful for hot-reload: parse the new file, then call engine.updateConfig().
+ */
+export function parsePolicyFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new MatimoError(`Cannot read policy file "${filePath}": ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new MatimoError(`Policy file "${filePath}" contains invalid YAML: ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    const result = PolicyFileSchema.safeParse(parsed ?? {});
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  \u2022 ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new MatimoError(`Policy file "${filePath}" is invalid:\n${issues}`, ErrorCode.INVALID_SCHEMA, { filePath, issues: result.error.issues });
+    }
+    return buildPolicyConfig(result.data);
+}
+function buildPolicyConfig(data) {
+    const config = {};
+    if (data.allowedDomains !== undefined)
+        config.allowedDomains = data.allowedDomains;
+    if (data.allowedCredentials !== undefined)
+        config.allowedCredentials = data.allowedCredentials;
+    if (data.allowedHttpMethods !== undefined)
+        config.allowedHttpMethods = data.allowedHttpMethods;
+    if (data.allowCommandTools !== undefined)
+        config.allowCommandTools = data.allowCommandTools;
+    if (data.allowFunctionTools !== undefined)
+        config.allowFunctionTools = data.allowFunctionTools;
+    if (data.protectedNamespaces !== undefined)
+        config.protectedNamespaces = data.protectedNamespaces;
+    if (data.enableHITL !== undefined)
+        config.enableHITL = data.enableHITL;
+    if (data.quarantineRiskLevels !== undefined)
+        config.quarantineRiskLevels = data.quarantineRiskLevels;
+    if (data.approvalTtlSeconds !== undefined)
+        config.approvalTtlSeconds = data.approvalTtlSeconds;
+    return config;
+}
+//# sourceMappingURL=policy-loader.js.map

package/dist/policy/policy-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.js","sourceRoot":"","sources":["../../src/policy/policy-loader.ts"],"names":[],"mappings":"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"}

package/dist/policy/risk-classifier.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Risk Classifier for Matimo tools.
+ *
+ * Pure function that classifies a tool's risk level based on its execution
+ * type, HTTP method, and approval requirements. No schema changes needed.
+ */
+import type { ToolDefinition } from '../core/schema';
+import type { RiskLevel } from './types';
+/**
+ * Classify the risk level of a tool based on its definition.
+ *
+ * - critical: arbitrary code execution (type: function)
+ * - high: shell execution (type: command), HTTP DELETE, or explicit requires_approval
+ * - medium: HTTP POST/PUT/PATCH (write operations)
+ * - low: HTTP GET, read-only tools
+ */
+export declare function classifyRisk(tool: ToolDefinition): RiskLevel;
+//# sourceMappingURL=risk-classifier.d.ts.map

package/dist/policy/risk-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-classifier.d.ts","sourceRoot":"","sources":["../../src/policy/risk-classifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAoC5D"}

package/dist/policy/risk-classifier.js

@@ -0,0 +1,47 @@
+/**
+ * Risk Classifier for Matimo tools.
+ *
+ * Pure function that classifies a tool's risk level based on its execution
+ * type, HTTP method, and approval requirements. No schema changes needed.
+ */
+/**
+ * Classify the risk level of a tool based on its definition.
+ *
+ * - critical: arbitrary code execution (type: function)
+ * - high: shell execution (type: command), HTTP DELETE, or explicit requires_approval
+ * - medium: HTTP POST/PUT/PATCH (write operations)
+ * - low: HTTP GET, read-only tools
+ */
+export function classifyRisk(tool) {
+    // Explicit override declared in the tool YAML takes precedence
+    if (tool.risk) {
+        return tool.risk;
+    }
+    const exec = tool.execution;
+    // Arbitrary code execution is always critical risk
+    if (exec.type === 'function') {
+        return 'critical';
+    }
+    // Shell commands are high risk (injection vectors)
+    if (exec.type === 'command') {
+        return 'high';
+    }
+    // HTTP tools: risk depends on method
+    if (exec.type === 'http') {
+        if (tool.requires_approval === true) {
+            return 'high';
+        }
+        const method = exec.method.toUpperCase();
+        if (method === 'DELETE') {
+            return 'high';
+        }
+        if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+            return 'medium';
+        }
+        // GET is low risk
+        return 'low';
+    }
+    // Unknown execution type — treat as high
+    return 'high';
+}
+//# sourceMappingURL=risk-classifier.js.map

package/dist/policy/risk-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-classifier.js","sourceRoot":"","sources":["../../src/policy/risk-classifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,+DAA+D;IAC/D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,IAAiB,CAAC;IAChC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;IAE5B,mDAAmD;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,mDAAmD;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qCAAqC;IACrC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;YACpC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YAChE,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,kBAAkB;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yCAAyC;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/policy/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Policy Engine types for Matimo Agent-Native SDK.
+ *
+ * The policy engine governs what tools agents can create, execute, and discover.
+ * Agents cannot mutate policy at runtime; the host configures it and may hot-reload via `updateConfig()`.
+ */
+import type { ToolDefinition } from '../core/schema';
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Three-tier classification for agent-created tool proposals.
+ *
+ * - `auto`: Can be created and used immediately (low-risk GET tools, no auth).
+ * - `approval-required`: Allowed but must be approved before execution
+ *   (tools with auth, POST/PUT/DELETE, external data writes).
+ * - `blocked`: Can never be created regardless of policy config
+ *   (reserved namespaces, function/command execution, SSRF targets,
+ *   tools referencing policy internals).
+ */
+export type PolicyTier = 'auto' | 'approval-required' | 'blocked';
+/**
+ * Identity and environment context passed by the host application.
+ * Matimo does not authenticate — this is whatever the caller provides.
+ */
+export interface PolicyContext {
+    /** Identifier for the calling agent (optional — SDK doesn't mandate identity) */
+    agentId?: string;
+    /** Deployment environment (e.g. 'dev', 'staging', 'prod') */
+    environment?: string;
+    /** Roles assigned to the caller (e.g. ['reader', 'writer', 'admin']) */
+    roles?: string[];
+    /** Extensible metadata for custom policy rules */
+    metadata?: Record<string, unknown>;
+}
+export type PolicyDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    riskLevel?: RiskLevel;
+} | {
+    allowed: 'pending_approval';
+    reason: string;
+    riskLevel: RiskLevel;
+    /** Tool name for the approval flow to reference */
+    toolName?: string;
+};
+/**
+ * Async callback invoked when a tool enters the quarantine/HITL state.
+ * Returns `true` if the admin approves, `false` if rejected.
+ * Integrators wire this to a UI, Slack message, or approval queue.
+ */
+export type HITLCallback = (request: HITLRequest) => Promise<boolean>;
+export interface HITLRequest {
+    toolName: string;
+    riskLevel: RiskLevel;
+    reason: string;
+    environment?: string;
+    agentId?: string;
+    /** Full tool definition for admin review */
+    toolDefinition?: unknown;
+}
+export interface Violation {
+    /** Machine-readable rule identifier (e.g. 'no-ssrf', 'reserved-namespace') */
+    rule: string;
+    /** Severity of the violation */
+    severity: RiskLevel;
+    /** Human-readable explanation */
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    violations: Violation[];
+}
+export interface ValidationContext {
+    /** Whether the tool comes from a trusted or untrusted path */
+    source: 'trusted' | 'untrusted';
+    /** Active policy configuration (defaults to empty/permissive) */
+    policy?: PolicyConfig;
+}
+/**
+ * Developer-configurable policy rules. All fields optional with conservative defaults.
+ */
+export interface PolicyConfig {
+    /** HTTP tool URL domain allowlist. If set, only these domains are permitted. */
+    allowedDomains?: string[];
+    /** Env var names that agent-created tools may reference for auth. */
+    allowedCredentials?: string[];
+    /** HTTP methods allowed for agent-created tools (default: ['GET', 'POST']). */
+    allowedHttpMethods?: string[];
+    /** Allow agent-created tools with execution type 'command' (default: false). */
+    allowCommandTools?: boolean;
+    /** Allow agent-created tools with execution type 'function' (default: false — always false for untrusted). */
+    allowFunctionTools?: boolean;
+    /** Tool name prefixes reserved for built-in tools (default: ['matimo_']). */
+    protectedNamespaces?: string[];
+    /**
+     * Enable quarantine/HITL for medium-risk tools in production.
+     * When true, `canCreate()` returns `pending_approval` instead of `allowed: false`
+     * for medium-risk tools, allowing a human reviewer to approve or reject.
+     * Default: false (original binary behavior preserved).
+     */
+    enableHITL?: boolean;
+    /**
+     * Risk levels eligible for HITL quarantine instead of outright rejection.
+     * Default: ['medium'] — critical/high are always blocked, low is always auto.
+     */
+    quarantineRiskLevels?: RiskLevel[];
+    /**
+     * Number of seconds after which an approval expires and the tool must be re-approved.
+     * If not set, approvals never expire.
+     */
+    approvalTtlSeconds?: number;
+}
+/**
+ * The PolicyEngine interface. Implementations are frozen at boot time and
+ * cannot be mutated by agents at runtime.
+ */
+export interface PolicyEngine {
+    /** Check whether this agent is allowed to execute a given tool. */
+    canExecute(context: PolicyContext, tool: ToolDefinition): PolicyDecision;
+    /** Check whether this agent is allowed to create/propose a tool definition. */
+    canCreate(context: PolicyContext, toolDef: ToolDefinition): PolicyDecision;
+    /**
+     * Update the policy configuration at runtime (hot-reload).
+     * Implementations should validate the new config before applying.
+     */
+    updateConfig?(config: PolicyConfig): void;
+    /** Filter a list of tools to only those this agent is allowed to see/use. */
+    filterForAgent(context: PolicyContext, tools: ToolDefinition[]): ToolDefinition[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/policy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"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"}

package/dist/policy/types.js

@@ -0,0 +1,8 @@
+/**
+ * Policy Engine types for Matimo Agent-Native SDK.
+ *
+ * The policy engine governs what tools agents can create, execute, and discover.
+ * Agents cannot mutate policy at runtime; the host configures it and may hot-reload via `updateConfig()`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matimo/core",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0",
   "description": "Core SDK for Matimo: Framework-agnostic YAML-driven tool ecosystem for AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
     }
   },
   "engines": {
@@ -54,14 +58,26 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.3",
-    "axios": "^1.13.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.15.2",
     "dotenv": "^17.2.3",
     "js-yaml": "^4.1.1",
     "winston": "^3.19.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"
   },
+  "peerDependencies": {
+    "@aws-sdk/client-secrets-manager": ">=3.0.0",
+    "node-vault": ">=0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "node-vault": {
+      "optional": true
+    },
+    "@aws-sdk/client-secrets-manager": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
@@ -69,14 +85,14 @@
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "eslint": "^9.39.2",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
     "langchain": "^1.2.18",
     "prettier": "^3.8.1",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.9",
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"

package/tools/matimo_approve_tool/definition.yaml

@@ -0,0 +1,36 @@
+name: matimo_approve_tool
+version: '1.0.0'
+description: Approve a draft tool for production use. Re-validates the tool, requires admin role, signs with HMAC, and updates the approval manifest.
+requires_approval: true
+tags:
+  - matimo
+  - meta
+  - approval
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name of the tool to approve
+  tool_dir:
+    type: string
+    required: false
+    description: Directory containing the tool (default ./matimo-tools)
+
+execution:
+  type: function
+  code: './matimo_approve_tool.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    name:
+      type: string
+    hash:
+      type: string
+    approvedAt:
+      type: string
+    message:
+      type: string

package/tools/matimo_approve_tool/matimo_approve_tool.ts

@@ -0,0 +1,90 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import {
+  validateToolDefinition,
+  validateToolContent,
+  ApprovalManifest,
+  getGlobalMatimoLogger,
+} from '@matimo/core';
+import type { Violation } from '@matimo/core';
+
+interface ApproveParams {
+  name: string;
+  tool_dir?: string;
+}
+
+interface ApproveResult {
+  success: boolean;
+  name?: string;
+  hash?: string;
+  approvedAt?: string;
+  message: string;
+}
+
+export default async function matimoApproveTool(
+  params: ApproveParams,
+  context?: { credentials?: Record<string, string> },
+): Promise<ApproveResult> {
+  const logger = getGlobalMatimoLogger();
+  const toolDir = params.tool_dir || './matimo-tools';
+
+  // Step 1: Read tool definition
+  const defPath = path.join(toolDir, params.name, 'definition.yaml');
+  if (!fs.existsSync(defPath)) {
+    return { success: false, message: `Tool not found: ${defPath}` };
+  }
+
+  const yamlContent = fs.readFileSync(defPath, 'utf-8');
+
+  // Step 2: Parse and validate
+  let tool;
+  try {
+    const parsed = yaml.load(yamlContent);
+    tool = validateToolDefinition(parsed);
+  } catch (err) {
+    return { success: false, message: `Validation failed: ${(err as Error).message}` };
+  }
+
+  // Step 3: Re-run content validator
+  const validation = validateToolContent(tool, { source: 'untrusted' });
+  const criticalOrHigh = validation.violations.filter(
+    (v: Violation) => v.severity === 'critical' || v.severity === 'high',
+  );
+  if (criticalOrHigh.length > 0) {
+    return {
+      success: false,
+      message: 'Tool has policy violations that must be resolved before approval',
+    };
+  }
+
+  // Step 4: Approve via manifest
+  const approvalDir = path.resolve(toolDir);
+  const manifest = new ApprovalManifest(
+    approvalDir,
+    context?.credentials?.MATIMO_APPROVAL_SECRET,
+  );
+
+  const hash = manifest.computeHash(yamlContent);
+  manifest.approve(params.name, hash);
+  const approval = manifest.getApproval(params.name);
+
+  // Step 5: Update status in YAML
+  const parsed = yaml.load(yamlContent) as Record<string, unknown>;
+  parsed.status = 'approved';
+  const updatedYaml = yaml.dump(parsed);
+  fs.writeFileSync(defPath, updatedYaml, 'utf-8');
+
+  logger.info('matimo_approve_tool: tool approved', {
+    name: params.name,
+    hash,
+  });
+
+  return {
+    success: true,
+    name: params.name,
+    hash,
+    approvedAt: approval?.approvedAt,
+    message: 'Tool approved. Effective after reload or immediately if auto-reload is active.',
+  };
+}

package/tools/matimo_create_skill/definition.yaml

@@ -0,0 +1,46 @@
+name: matimo_create_skill
+version: '1.0.0'
+description: >-
+  Create a new skill following the Agent Skills specification
+  (https://agentskills.io/specification). Validates name (lowercase, hyphens,
+  max 64 chars), YAML frontmatter (name, description required), and enforces
+  that the frontmatter name matches the directory name.
+requires_approval: true
+tags:
+  - matimo
+  - meta
+  - skill
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: >-
+      Skill directory name. Must be lowercase letters, numbers, and hyphens
+      only. Max 64 characters. Must not start/end with a hyphen or contain
+      consecutive hyphens. Must match the name field in the YAML frontmatter.
+  content:
+    type: string
+    required: true
+    description: >-
+      The full SKILL.md content including YAML frontmatter (--- delimited) and
+      markdown body. Required frontmatter fields: name, description. Optional:
+      license, compatibility, metadata, allowed-tools.
+  target_dir:
+    type: string
+    required: false
+    description: Directory to create the skill in (default ./matimo-tools/skills)
+
+execution:
+  type: function
+  code: './matimo_create_skill.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    path:
+      type: string
+    message:
+      type: string