@farris/skills

Farris 知识生态与 AI Coding Agent 技能管理 CLI 工具。

@farris/skills 是一个面向 AI 辅助编程与企业级组件知识管理的命令行工具。它借鉴了 TanStack Agent Skills 的设计理念，采用代码与知识同仓分发（In-Package Colocation）架构，让 AI Agent（如 Antigravity、Claude Code、Cursor、Copilot 等）在开发 Farris 业务应用时能够即时发现组件技能、按需动态加载规约、精准生成代码且无幻觉。

核心特性

• 📦 包内共生（In-Package Colocation）：每个组件库（如 @farris/gantt、@abc/te-grid）自带 skills/<name>/SKILL.md，技能与组件代码版本 100% 同步演进。
• 🔍 双层知识架构：
  • 索引层（Registry Catalog）：轻量级能力目录，供开发者或 Agent 快速检索“需要用什么组件”。
  • 加载层（In-Package Detail）：仅在安装组件后按需提取 Markdown 技能上下文，避免上下文窗口爆炸。
• 🚀 零侵入消费：无需入侵宿主业务工程，支持直接通过 npx @farris/skills 即开即用。
• 🛠️ 全链路配套：支持扫描已安装技能（list）、标准管道输出技能（load）、云端检索（search）与工程健康诊断（doctor）。

安装与使用

免安装直接运行（推荐）

# 查看已安装技能
npx @farris/skills list

# 检索云端可用技能与组件
npx @farris/skills search 甘特图

# 加载指定组件的技能规约
npx @farris/skills load @farris/gantt#gantt

# 环境与工程健康诊断
npx @farris/skills doctor

全局安装

npm install -g @farris/skills
# 或
pnpm add -g @farris/skills

farris-skills --help

命令详解

1. list - 扫描本地工程技能

扫描当前工程 node_modules/ 下所有带有 skills/*/SKILL.md 的 npm 包并列出。

# 格式化表格显示
farris-skills list

# 输出为 JSON（便于 Agent 解析）
farris-skills list --json

2. load - 读取指定技能规约

读取并输出指定技能规约的 Markdown 内容（stdout）。可被 Agent 执行以动态注入到 Prompt 上下文中。

# 输出 Markdown 文本
farris-skills load @farris/gantt#gantt

# 仅输出本地物理路径
farris-skills load @farris/gantt#gantt --path

3. search - 检索云端能力目录

通过关键词（支持中英文、拼音、标签）在能力中心目录中检索匹配的组件与技能。

# 检索甘特图相关组件
farris-skills search "甘特图"

# 指定自定义 catalog.json 路径
farris-skills search "表格" --catalog ./data/catalog.json

4. doctor - 工程健康诊断

检查当前 Node 版本、工程环境、node_modules 存在性及已安装的技能包数量。

farris-skills doctor

组件开发者接入指南

若希望将您的业务组件纳入 Farris 知识生态，只需遵循以下规约：

1. 目录结构

在组件源码根目录下创建 skills/<skill-name>/SKILL.md：

my-farris-component/
├── package.json
├── src/
│   └── index.ts
└── skills/
    └── my-component/
        ├── SKILL.md
        └── references/       # 可选：详细 API、用例等
            └── examples.md

2. 规范 frontmatter

在 SKILL.md 顶部使用标准的 YAML Frontmatter 声明：

---
name: my-component
description: 适用于复杂业务表单的联动与校验场景
keywords:
  - ibp-intent
  - farris
  - 表单联动
  - 动态表单
---

# My Component Skill 规约与用法
...

3. 配置 package.json

确保 package.json 中的 keywords 包含 ibp-intent，并且 files 字段包含 skills 目录：

{
  "name": "@farris/my-component",
  "version": "1.0.0",
  "keywords": [
    "ibp-intent",
    "farris",
    "表单联动"
  ],
  "files": [
    "dist",
    "skills"
  ]
}

发布后，企业注册表（registry）会自动识别并收录该组件，开发者和 Agent 可立即通过 @farris/skills 检索和使用！

许可证

MIT