agentsync

分类: 工具与效率 | 上传者: yelmuratoff | 下载: 0 | 版本: v1.0（最新）

创建或编辑 AgentSync 配置 - 规则、技能、命令、代理、设置、MCP 或工具配置。在添加规则、创建技能、编写命令、定义代理、编辑权限、配置工具或设置 .ai/ 目录时使用。 --- # 使用 AgentSync 以 AgentSync 格式创建和维护 AI 代理指令。 ## 结构 ``` .ai/src/ # 事实来源。仅在此处编辑。 ├── AGENTS.md # 代理身份：角色、方法、原则 ├── Rules/ # 始终开启的约束（每个主题一个文件） │ ├── core.md │ └── testing.md ├── Skills/ # 按需配方（每个技能一个目录） │ └── deploy/ │ └── SKILL.md ├── Commands/ # 自定义斜杠命令（.md 文件） │ ├── review.md │ └── fix-issue.md ├── Agents/ # 子代理角色（.md 文件） │ └── code-reviewer.md ├── settings/ # 工具特定权限 (JSON) │ └── claude.json ├── mcp/ # MCP 服务器配置 (JSON) │ └── claude.json ├── hooks/ # 事件钩子（JSON） │ ├──cursor.json │ └── codex.json └──tools/ # 工具配置（claude.yaml、cursor.yaml 等） ``` 编辑后，运行 `agentsyncsync` 分发到所有工具。 ## 编写AGENTS.md 代理的身份。每句话都应该改变行为。 - **具体一点** — “高级 React/TypeScript 工程师”而不是“软件工程师”。 - **包括堆栈** — 代理需要知道它正在处理什么。 - **可行的原则** — “更喜欢组合而不是继承”而不是“编写好的代码”。 - **不该做什么** — 约束通常比说明更有用。 - 60 行以下。 No generic filler. ## 编写规则永远在线的约束。 `.ai/src/rules/` 中每个主题一个文件。 - **每个文件一个问题** — `testing.md`、`security.md`。不是“一切.md”。 - **命令性和具体性** — “对数据库列使用 `snake_case`

更新日志: Source: GitHub https://github.com/yelmuratoff/agent_sync

目录结构

当前层级: tree/main/example/.ai/src/skills/agentsync/

📄 SKILL.md 7.5 KB

SKILL.md

---
name: agentsync
description: >
  Create or edit AgentSync configuration — rules, skills, commands, agents, settings, MCP, or tool configs.
  USE WHEN adding rules, creating skills, writing commands, defining agents, editing permissions, configuring tools, or setting up .ai/ directory.
---

# Working with AgentSync

Create and maintain AI agent instructions in the AgentSync format.

## Structure

```
.ai/src/                        # Source of truth. Edit ONLY here.
├── AGENTS.md                   # Agent identity: role, approach, principles
├── rules/                      # Always-on constraints (one file per topic)
│   ├── core.md
│   └── testing.md
├── skills/                     # On-demand recipes (one directory per skill)
│   └── deploy/
│       └── SKILL.md
├── commands/                   # Custom slash commands (.md files)
│   ├── review.md
│   └── fix-issue.md
├── agents/                     # Subagent personas (.md files)
│   └── code-reviewer.md
├── settings/                   # Tool-specific permissions (JSON)
│   └── claude.json
├── mcp/                        # MCP server configs (JSON)
│   └── claude.json
├── hooks/                      # Event hooks (JSON)
│   ├── cursor.json
│   └── codex.json
└── tools/                      # Tool configs (claude.yaml, cursor.yaml, etc.)
```

After editing, run `agentsync sync` to distribute to all tools.

## Writing AGENTS.md

The agent's identity. Every sentence should change behavior.

- **Be specific** — "Senior React/TypeScript Engineer" not "software engineer".
- **Include the stack** — The agent needs to know what it's working with.
- **Actionable principles** — "Prefer composition over inheritance" not "Write good code".
- **What NOT to do** — Constraints are often more useful than instructions.
- Under 60 lines. No generic filler.

## Writing Rules

Always-on constraints. One file per topic in `.ai/src/rules/`.

- **One concern per file** — `testing.md`, `security.md`. Not `everything.md`.
- **Imperative and specific** — "Use `snake_case` for DB columns" not "Follow naming conventions".
- **Constraints, not tutorials** — Say what to do and what not to do. Don't explain concepts.
- **Scannable in 30 seconds** — If too long, split it.

## Writing Skills — The Most Important Part

Skills are the highest-leverage configuration. A skill is a directory with a `SKILL.md`.

### The description is a TRIGGER, not a summary

The agent scans every skill description at startup. Vague = invisible.

Bad: `description: "Helps with testing"`
Good: `description: "Write unit and integration tests for new features. USE WHEN adding tests, writing test cases, or asked to verify behavior."`

Always include `USE WHEN` with concrete trigger conditions.

### Frontmatter fields

```yaml
---
name: skill-name # Required. Lowercase, kebab-case.
description: > # Required. Trigger description with USE WHEN clause.
  What this skill does.
  USE WHEN [concrete trigger conditions].


# Optional fields (tool-specific, passed through by agentsync):
# context: fork                 # Run in isolated subagent (Claude Code)
# allowed-tools: [Read, Grep]   # Limit available tools (Claude Code)
# paths: ["src/api/**"]         # Only activate for matching paths
---
```

### Structure of a good skill

```markdown
---
name: example
description: >
  [What it does]. USE WHEN [triggers].
---

# Skill Name

[One line: what this skill does and when.]

## Steps

1. [Concrete numbered steps]
2. [With real commands and paths]

## Gotchas

- [Every mistake the agent has made using this skill]
- [Edge cases and common pitfalls]
```

### The Gotchas section

This is the highest-signal content. Every time the agent makes a mistake, add it to Gotchas. This section prevents the same error from happening twice.

### Rule of Three

Don't create a skill for everything. If you've done something three times manually, then create a skill.

## Writing Commands

Custom slash commands. Each `.md` file in `.ai/src/commands/` becomes a command (e.g., `review.md` → `/project:review`).

```markdown
---
description: What this command does (shown in command list)
argument-hint: "<optional-arg>"
---

[Prompt content with instructions for the AI.]
```

Key features:

- `$ARGUMENTS` — replaced with text after the command name.
- `` !`shell command` `` — runs a shell command and embeds output into the prompt.
- Keep commands focused — one workflow per command.
- Good commands: `review`, `fix-issue`, `deploy`, `migrate`.

## Writing Agents (Subagent Personas)

Specialized AI personas in `.ai/src/agents/`. Each `.md` file defines an agent with its own system prompt and tool restrictions.

```markdown
---
name: code-reviewer
description: >
  Expert code reviewer. USE PROACTIVELY when reviewing PRs or validating implementations.
model: sonnet # Cheaper model for focused tasks
tools: [Read, Grep, Glob] # Restrict to read-only tools
---

You are a senior code reviewer...
```

Guidelines:

- Restrict `tools` to what the agent actually needs. Read-only agents shouldn't have Write.
- Use `model: sonnet` or `model: haiku` for focused tasks to save cost.
- Only create agents for distinct specializations — don't duplicate what skills already do.

## Settings & Permissions

Tool-specific settings in `.ai/src/settings/`. Each file is named after the tool and copied directly.

Example `claude.json`:

```json
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read", "Write", "Edit"],
    "deny": ["Bash(rm -rf *)", "Read(.env)"]
  }
}
```

## MCP Configs

MCP server configurations in `.ai/src/mcp/`. Each file is named after the tool.

Example `claude.json`:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}
```

## Inline Options

For tools without separate rules/skills directories, use inline options:

- **`inline_into_agents: true`** (rules) — appends lightweight rule REFERENCES (name + title) to the agents file instead of syncing rules as separate files. Used by: Codex, Amp, Devin, Gemini.
- **`inline_into_agents: true`** (skills) — appends lightweight skill INDEX (name + description) to the agents file instead of syncing skills as directories. Used by: Junie, Cline, Amazon Q, Augment, Tabnine, Aider, Zed, Continue.
- **`prepend_agents: true`** (rules with `merge_to_file`) — prepends AGENTS.md content before merged rules in a single output file. Used by: Aider, Zed, Continue.
- **`00-context.md` pattern** — for directory-based tools without separate agents support, AGENTS.md is copied as `00-context.md` inside the rules directory. Used by: Cline, Amazon Q, Augment, Tabnine.

## Adding a New Tool

1. Copy `.ai/src/tools/_TEMPLATE.yaml` to `.ai/src/tools/<tool>.yaml`.
2. Set `name`, `enabled: true`, and configure `targets`.
3. Run `agentsync sync --only <tool>` to test.

## Gotchas

- Always edit files in `.ai/src/`, never in generated directories (`.claude/`, `.cursor/`, etc.).
- Run `agentsync sync` after every change to distribute updates.
- Tool-specific frontmatter fields (like `context: fork`) are passed through as-is — agentsync doesn't validate them.
- Don't create overlapping skills — if two skills could trigger on the same task, merge them or make descriptions mutually exclusive.
- Commands and agents only work in tools that support them (Claude, Gemini for commands; Claude, Copilot for agents).
- Settings and MCP files are per-tool — each tool has its own format.

登录后下载/点赞/收藏 ❤ 5 | ★ 0

agentsync

目录结构

SKILL.md

举报内容

提示