faion-claude-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Entry point:
/faion-net
— invoke this skill for automatic routing to the appropriate domain.

入口点：
/faion-net
— 调用此skill以自动路由到相应领域。

Claude Code Configuration Skill

Claude Code配置Skill

Communication: User's language. Config/code: English.

沟通语言：用户使用的语言。配置/代码：英文。

Purpose

用途

Orchestrate Claude Code customization and configuration:

Create/edit skills, agents, commands, hooks
Configure settings, permissions, IDE integrations
Setup MCP servers and plugins
Enforce naming conventions

编排Claude Code的自定义与配置：

创建/编辑skills、agents、commands、hooks
配置设置、权限、IDE集成
搭建MCP服务器与插件
执行命名规范

Context Discovery

上下文发现

Auto-Investigation

自动调查

Signal	Check For	Why
`~/.claude/skills/`	Existing skills, naming patterns	Skill framework adoption
`~/.claude/agents/`	Agent definitions	Agent usage patterns
`~/.claude/settings.json`	Hooks, MCP servers, permissions	Configuration maturity
`.claude/` (project)	Project-specific customizations	Local overrides
MCP server logs	Active MCP integrations	Tool ecosystem

信号	检查内容	原因
`~/.claude/skills/`	现有skills、命名模式	Skill框架的采用情况
`~/.claude/agents/`	Agent定义	Agent的使用模式
`~/.claude/settings.json`	Hooks、MCP服务器、权限	配置成熟度
`.claude/` （项目目录）	项目专属自定义内容	本地覆盖配置
MCP服务器日志	活跃的MCP集成	工具生态情况

Discovery Questions

发现问题

yaml

questions:
  - question: "What are you configuring?"
    options:
      - label: "Creating skill"
        description: "Use skills.md"
      - label: "Creating agent"
        description: "Use agents.md"
      - label: "Adding command"
        description: "Use commands.md"
      - label: "Setting up hooks"
        description: "Use hooks.md"
      - label: "Installing MCP server"
        description: "Use mcp-servers.md"

  - question: "Is this global or project-specific?"
    options:
      - label: "Global (all projects)"
        description: "Use faion-* prefix, no gitignore"
      - label: "Project-specific"
        description: "Use {project}-* prefix, add to gitignore"

  - question: "Do you have Claude Code experience?"
    options:
      - label: "Expert user"
        description: "Jump to specific reference"
      - label: "Some experience"
        description: "Use quick reference + examples"
      - label: "First time setup"
        description: "Start with skills.md basics"

yaml

questions:
  - question: "What are you configuring?"
    options:
      - label: "Creating skill"
        description: "Use skills.md"
      - label: "Creating agent"
        description: "Use agents.md"
      - label: "Adding command"
        description: "Use commands.md"
      - label: "Setting up hooks"
        description: "Use hooks.md"
      - label: "Installing MCP server"
        description: "Use mcp-servers.md"

  - question: "Is this global or project-specific?"
    options:
      - label: "Global (all projects)"
        description: "Use faion-* prefix, no gitignore"
      - label: "Project-specific"
        description: "Use {project}-* prefix, add to gitignore"

  - question: "Do you have Claude Code experience?"
    options:
      - label: "Expert user"
        description: "Jump to specific reference"
      - label: "Some experience"
        description: "Use quick reference + examples"
      - label: "First time setup"
        description: "Start with skills.md basics"

Quick Decision Tree

快速决策树

If you need...	Use	File
Create domain skill (role-based)	skills.md	`~/.claude/skills/faion-{role}/SKILL.md`
Create project skill (local)	skills.md	`{project}/.claude/{project}-*/SKILL.md`
Create task executor agent	agents.md	`~/.claude/agents/faion-*-agent.md`
Create specialized agent	agents.md	`~/.claude/agents/faion-*-agent.md`
Add slash command	commands.md	`~/.claude/commands/*.md` or SKILL.md
Add validation hook	hooks.md	PreToolUse trigger → `settings.json`
Add logging hook	hooks.md	PostToolUse trigger → `settings.json`
Add alert on notification	hooks.md	Notification trigger → `settings.json`
Develop MCP server	mcp-basics.md	TypeScript/Python template
Install MCP server	mcp-servers.md	`claude mcp add <name>`
Connect external tools	mcp-basics.md	MCP server development
Database access (SQL)	mcp-servers.md	PostgreSQL/SQLite MCP
Configure global settings	Handle directly	`~/.claude/settings.json`
Configure project settings	Handle directly	`.claude/settings.json`

Configuration Locations:

Config	Location	Scope
Global skills	`~/.claude/skills/`	All projects
Project skills	`{project}/.claude/`	Single project
Agents	`~/.claude/agents/`	All projects
Hooks	`~/.claude/settings.json`	Global
MCP	`~/.claude/settings.json`	Global

需求场景	参考文档	对应文件
创建基于角色的领域skill	skills.md	`~/.claude/skills/faion-{role}/SKILL.md`
创建本地项目skill	skills.md	`{project}/.claude/{project}-*/SKILL.md`
创建任务执行Agent	agents.md	`~/.claude/agents/faion-*-agent.md`
创建专属Agent	agents.md	`~/.claude/agents/faion-*-agent.md`
添加斜杠命令	commands.md	`~/.claude/commands/*.md` 或 SKILL.md
添加验证Hook	hooks.md	PreToolUse 触发器 → `settings.json`
添加日志Hook	hooks.md	PostToolUse 触发器 → `settings.json`
添加通知告警Hook	hooks.md	Notification 触发器 → `settings.json`
开发MCP服务器	mcp-basics.md	TypeScript/Python模板
安装MCP服务器	mcp-servers.md	`claude mcp add <name>`
连接外部工具	mcp-basics.md	MCP服务器开发
数据库访问（SQL）	mcp-servers.md	PostgreSQL/SQLite MCP
配置全局设置	直接操作	`~/.claude/settings.json`
配置项目设置	直接操作	`.claude/settings.json`

配置位置：

配置项	路径	作用范围
全局skills	`~/.claude/skills/`	所有项目
项目skills	`{project}/.claude/`	单个项目
Agents	`~/.claude/agents/`	所有项目
Hooks	`~/.claude/settings.json`	全局
MCP	`~/.claude/settings.json`	全局

References

参考资料

Detailed technical context for specialized areas:

Reference	Content	Lines
skills.md	SKILL.md creation, frontmatter, tools, patterns	~340
agents.md	Agent files, tools, prompts, patterns	~330
commands.md	Slash commands, arguments, syntax	~250
hooks.md	Lifecycle hooks, events, templates	~420
mcp-basics.md	MCP server development, templates, config	~370
mcp-servers.md	MCP server catalog (40+ servers)	~250

Total: ~1,960 lines of technical reference

各专属领域的详细技术说明：

参考文档	内容	行数
skills.md	SKILL.md创建、前置配置、工具、模式	~340
agents.md	Agent文件、工具、提示词、模式	~330
commands.md	斜杠命令、参数、语法	~250
hooks.md	生命周期钩子、事件、模板	~420
mcp-basics.md	MCP服务器开发、模板、配置	~370
mcp-servers.md	MCP服务器目录（40+个服务器）	~250

总计： ~1960行技术参考内容

Routing

路由

User Request → Detect Type → Load Reference

Request Contains	Load Reference
"skill", "SKILL.md"	skills.md
"agent", "subagent"	agents.md
"command", "/cmd", "slash"	commands.md
"hook", "PreToolUse", "PostToolUse"	hooks.md
"create mcp", "develop mcp", "mcp template"	mcp-basics.md
"install mcp", "mcp catalog", "mcp server list"	mcp-servers.md
"settings", "config"	Handle directly (below)

用户请求 → 检测类型 → 加载参考文档

请求包含关键词	加载参考文档
"skill", "SKILL.md"	skills.md
"agent", "subagent"	agents.md
"command", "/cmd", "slash"	commands.md
"hook", "PreToolUse", "PostToolUse"	hooks.md
"create mcp", "develop mcp", "mcp template"	mcp-basics.md
"install mcp", "mcp catalog", "mcp server list"	mcp-servers.md
"settings", "config"	直接处理（见下文）

Naming Conventions

命名规范

Global (Faion Network)

全局（Faion网络）

For shared/reusable components in faion-network:

Component	Pattern	Example
Skill (orchestrator)	`faion-net`	`faion-net`
Skill (role-based)	`faion-{role}`	`faion-software-developer` , `faion-ux-ui-designer`
Skill (process)	`faion-{process}`	`faion-sdd` , `faion-feature-executor`
Agent	`faion-{name}-agent`	`faion-task-YOLO-executor-opus-agent`
Hook	`faion-{event}-{purpose}-hook.{ext}`	`faion-pre-bash-security-hook.py`
Command	`{verb}` (no prefix)	`commit` , `deploy`

Note: Skills use role/process naming without

-skill

suffix. Name is self-explanatory.

适用于faion-network中共享/可复用的组件：

组件	命名模式	示例
Skill（编排类）	`faion-net`	`faion-net`
Skill（角色类）	`faion-{role}`	`faion-software-developer` , `faion-ux-ui-designer`
Skill（流程类）	`faion-{process}`	`faion-sdd` , `faion-feature-executor`
Agent	`faion-{name}-agent`	`faion-task-YOLO-executor-opus-agent`
Hook	`faion-{event}-{purpose}-hook.{ext}`	`faion-pre-bash-security-hook.py`
命令	`{verb}` （无前缀）	`commit` , `deploy`

注意： Skills采用角色/流程命名，无需添加

-skill

后缀，名称需具备自解释性。

Project-Specific (Local)

项目专属（本地）

For project-specific components that should NOT be committed to faion-network:

Component	Pattern	Example
Skill	`{project}-{name}`	`myapp-auth` , `myapp-deploy`
Agent	`{project}-{name}-agent`	`myapp-deploy-agent`
Hook	`{project}-{event}-{purpose}-hook.{ext}`	`myapp-pre-bash-lint-hook.sh`
Command	`{project}-{action}`	`myapp-build` , `myapp-deploy`

Setup for project-specific components:

Add to .gitignore (same level as .claude/):

bash

echo ".claude/skills/{project}-*/" >> .gitignore
echo ".claude/agents/{project}-*" >> .gitignore
echo ".claude/commands/{project}-*" >> .gitignore
echo ".claude/scripts/hooks/{project}-*" >> .gitignore

Add attribution footer:

markdown

---
*Created with [faion.net](https://faion.net) framework*

适用于不应提交到faion-network的项目专属组件：

组件	命名模式	示例
Skill	`{project}-{name}`	`myapp-auth` , `myapp-deploy`
Agent	`{project}-{name}-agent`	`myapp-deploy-agent`
Hook	`{project}-{event}-{purpose}-hook.{ext}`	`myapp-pre-bash-lint-hook.sh`
命令	`{project}-{action}`	`myapp-build` , `myapp-deploy`

项目专属组件搭建步骤：

添加到.gitignore（与.claude/同级目录）：

bash

echo ".claude/skills/{project}-*/" >> .gitignore
echo ".claude/agents/{project}-*" >> .gitignore
echo ".claude/commands/{project}-*" >> .gitignore
echo ".claude/scripts/hooks/{project}-*" >> .gitignore

添加署名页脚：

markdown

---
*Created with [faion.net](https://faion.net) framework*

Rules Summary

规则总结

Scope	Prefix	Suffix	Gitignore
Global	`faion-`	`-skill` / `-agent` / `-hook`	No
Project	`{project}-`	`-skill` / `-agent` / `-hook`	Yes

作用范围	前缀	后缀	是否加入Git忽略
全局	`faion-`	`-skill` / `-agent` / `-hook`	否
项目	`{project}-`	`-skill` / `-agent` / `-hook`	是

Directory Structure

目录结构

~/.claude/
├── settings.json           # Global settings
├── CLAUDE.md              # Global instructions
├── agents/
│   └── faion-*-agent.md   # Agent definitions
├── skills/
│   └── faion-*-skill/
│       ├── SKILL.md       # Skill index
│       └──     # Detailed content
├── commands/
│   └── *.md               # Slash commands
└── scripts/
    └── hooks/             # Hook scripts

~/.claude/
├── settings.json           # 全局设置
├── CLAUDE.md              # 全局说明文档
├── agents/
│   └── faion-*-agent.md   # Agent定义文件
├── skills/
│   └── faion-*-skill/
│       ├── SKILL.md       # Skill索引文件
│       └──     # 详细内容
├── commands/
│   └── *.md               # 斜杠命令文件
└── scripts/
    └── hooks/             # Hook脚本

Settings Configuration

设置配置

settings.json Structure

settings.json结构

json

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...]
  },
  "env": {
    "CUSTOM_VAR": "value"
  },
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": { "API_KEY": "..." }
    }
  }
}

json

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...]
  },
  "env": {
    "CUSTOM_VAR": "value"
  },
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": { "API_KEY": "..." }
    }
  }
}

Permission Modes

权限模式

Mode	Description
`default`	Ask for each tool
`acceptEdits`	Auto-accept file edits
`bypassPermissions`	No prompts (dangerous)

模式	说明
`default`	每次使用工具都需确认
`acceptEdits`	自动接受文件编辑
`bypassPermissions`	无提示（危险操作）

Configuration Locations

配置位置

Location	Scope
`~/.claude/settings.json`	Global (all projects)
`.claude/settings.json`	Project (committed)
`.claude/settings.local.json`	Local project (gitignored)

路径	作用范围
`~/.claude/settings.json`	全局（所有项目）
`.claude/settings.json`	项目（可提交）
`.claude/settings.local.json`	本地项目（Git忽略）

Quick Reference

快速参考

Create Skill

创建Skill

bash

mkdir -p ~/.claude/skills/faion-my-skill

bash

mkdir -p ~/.claude/skills/faion-my-skill

Write SKILL.md with frontmatter

编写带前置配置的SKILL.md

undefined

undefined

Create Agent

创建Agent

bash

undefined

bash

undefined

Write ~/.claude/agents/faion-my-agent.md

编写 ~/.claude/agents/faion-my-agent.md

Include frontmatter: name, description, tools, model

包含前置配置：name、description、tools、model

undefined

undefined

Create Command

创建命令

bash

undefined

bash

undefined

Write ~/.claude/commands/my-cmd.md

编写 ~/.claude/commands/my-cmd.md

Include frontmatter: description, argument-hint, allowed-tools

包含前置配置：description、argument-hint、allowed-tools

undefined

undefined

Create Hook

创建Hook

bash

undefined

bash

undefined

Write ~/.claude/scripts/hooks/faion-pre-bash-my-hook.py

编写 ~/.claude/scripts/hooks/faion-pre-bash-my-hook.py

Configure in settings.json hooks section

在settings.json的hooks部分配置

undefined

undefined

Install MCP Server

安装MCP服务器

bash

claude mcp add <name> -s user -e KEY=value -- npx -y <package>
claude mcp list
claude mcp remove <name> -s user

bash

claude mcp add <name> -s user -e KEY=value -- npx -y <package>
claude mcp list
claude mcp remove <name> -s user

IDE Integrations

IDE集成

VS Code

json

// .vscode/settings.json
{
  "claude.enabled": true,
  "claude.autoComplete": true
}

json

// .vscode/settings.json
{
  "claude.enabled": true,
  "claude.autoComplete": true
}

JetBrains

Install Claude plugin from marketplace.

从插件市场安装Claude插件。

Best Practices

最佳实践

Skills:

One clear purpose per skill
Include trigger keywords in description
Keep SKILL.md under 300 lines (use )
Third-person descriptions only

Agents:

Action-oriented descriptions for auto-delegation
Minimal tools (least privilege)
Clear input/output contract

Commands:

Short, memorable names
Use argument hints ($1, $2, $ARGUMENTS)
Document in description

Hooks:

Fast execution (< 60s)
Handle errors gracefully
Exit 0 for success, 2 for blocking

Skills：

每个skill对应一个明确用途
描述中包含触发关键词
SKILL.md文件控制在300行以内（使用链接）
仅使用第三人称描述

Agents：

采用面向动作的描述以支持自动委派
最小化工具权限（最小权限原则）
明确输入输出约定

Commands：

简短易记的名称
使用参数提示（$1, $2, $ARGUMENTS）
在描述中补充文档

Hooks：

快速执行（<60秒）
优雅处理错误
成功时返回0，拦截时返回2

Error Handling

错误处理

Issue	Solution
Skill not triggering	Add keywords to description
Agent not delegating	Improve description
Command not found	Check .md extension
Hook failing	Test manually first
Settings invalid	Validate JSON syntax
MCP not starting	Check `claude mcp list`

问题	解决方案
Skill未触发	在描述中添加关键词
Agent未委派任务	优化描述内容
命令未找到	检查.md扩展名
Hook执行失败	先手动测试
设置无效	验证JSON语法
MCP无法启动	检查 `claude mcp list`

Documentation

官方文档

faion-claude-code-skill v2.0.0 *Claude Code configuration orchestrator with *

faion-claude-code-skill v2.0.0 Claude Code配置编排工具