Migrate from Claude Code to OpenCode structure
- Move legacy content to legacy/ folder (old, old2, docs, learnings, scripts) - Create new .opencode/ structure with skills/, tools/, agents/ folders - Update Makefile to symlink to ~/.config/opencode/ instead of ~/.claude/ - Update Makefile to manage skills, tools, and agents (remove settings.json) - Simplify install/uninstall (no backup logic) - Add README.md documenting the new structure - Keep settings.json as historical reference
This commit is contained in:
278
legacy/old2/skills/reference/frontmatter-fields.md
Normal file
278
legacy/old2/skills/reference/frontmatter-fields.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Frontmatter Fields Reference
|
||||
|
||||
Complete documentation of all available frontmatter fields for skills and agents.
|
||||
|
||||
## Skill Frontmatter
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `name`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Format:** Lowercase, hyphens only, no spaces
|
||||
- **Max length:** 64 characters
|
||||
- **Must match:** Directory name
|
||||
- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
|
||||
- **Example:** `work-issue`, `code-review`, `gitea`
|
||||
|
||||
#### `description`
|
||||
- **Type:** string (multiline supported with `>`)
|
||||
- **Required:** Yes
|
||||
- **Max length:** 1024 characters
|
||||
- **Cannot contain:** XML tags
|
||||
- **Should include:**
|
||||
- What the skill does
|
||||
- When to use it
|
||||
- Trigger conditions
|
||||
- **Example:**
|
||||
```yaml
|
||||
description: >
|
||||
View, create, and manage Gitea issues and pull requests.
|
||||
Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
|
||||
```
|
||||
|
||||
#### `user-invocable`
|
||||
- **Type:** boolean
|
||||
- **Required:** Yes
|
||||
- **Values:** `true` or `false`
|
||||
- **Usage:**
|
||||
- `true`: User can trigger with `/skill-name`
|
||||
- `false`: Background skill, auto-loaded when needed
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### `model`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `haiku`, `sonnet`, `opus`
|
||||
- **Default:** Inherits from parent (usually haiku)
|
||||
- **Guidance:** Default to `haiku`, only upgrade if needed
|
||||
- **Example:**
|
||||
```yaml
|
||||
model: haiku # 12x cheaper than sonnet
|
||||
```
|
||||
|
||||
#### `argument-hint`
|
||||
- **Type:** string
|
||||
- **Required:** No (only for user-invocable skills)
|
||||
- **Format:** `<required>` for required params, `[optional]` for optional
|
||||
- **Shows in UI:** Helps users know what arguments to provide
|
||||
- **Example:**
|
||||
```yaml
|
||||
argument-hint: <issue-number>
|
||||
argument-hint: <issue-number> [optional-title]
|
||||
```
|
||||
|
||||
#### `context`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `fork`
|
||||
- **Usage:** Set to `fork` for skills needing isolated context
|
||||
- **When to use:** Heavy exploration tasks that would pollute main context
|
||||
- **Example:**
|
||||
```yaml
|
||||
context: fork # For arch-review-repo, deep exploration
|
||||
```
|
||||
|
||||
#### `allowed-tools`
|
||||
- **Type:** list of strings
|
||||
- **Required:** No
|
||||
- **Usage:** Restrict which tools the skill can use
|
||||
- **Example:**
|
||||
```yaml
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Grep
|
||||
```
|
||||
- **Note:** Rarely used, most skills have all tools
|
||||
|
||||
## Agent Frontmatter
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `name`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Same rules as skill name**
|
||||
|
||||
#### `description`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Should include:**
|
||||
- What the agent does
|
||||
- When to spawn it
|
||||
- **Example:**
|
||||
```yaml
|
||||
description: >
|
||||
Automated code review of pull requests for quality, bugs, security, and style.
|
||||
Spawn when reviewing PRs or checking code quality.
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### `model`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
|
||||
- **Default:** `inherit` (uses parent's model)
|
||||
- **Guidance:**
|
||||
- Default to `haiku` for simple agents
|
||||
- Use `sonnet` for balanced performance
|
||||
- Reserve `opus` for deep reasoning
|
||||
- **Example:**
|
||||
```yaml
|
||||
model: haiku # Fast and cheap for code review checklist
|
||||
```
|
||||
|
||||
#### `skills`
|
||||
- **Type:** comma-separated list of skill names (not paths)
|
||||
- **Required:** No
|
||||
- **Usage:** Auto-load these skills when agent spawns
|
||||
- **Format:** Just skill names, not paths
|
||||
- **Example:**
|
||||
```yaml
|
||||
skills: gitea, issue-writing, code-review
|
||||
```
|
||||
- **Note:** Agent runtime loads skills automatically
|
||||
|
||||
#### `disallowedTools`
|
||||
- **Type:** list of tool names
|
||||
- **Required:** No
|
||||
- **Common use:** Make agents read-only
|
||||
- **Example:**
|
||||
```yaml
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
```
|
||||
- **When to use:** Analysis agents that shouldn't modify code
|
||||
|
||||
#### `permissionMode`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `default`, `bypassPermissions`
|
||||
- **Usage:** Rarely used, for agents that need to bypass permission prompts
|
||||
- **Example:**
|
||||
```yaml
|
||||
permissionMode: bypassPermissions
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Minimal User-Invocable Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: dashboard
|
||||
description: Show open issues, PRs, and CI status.
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
### Full-Featured Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: work-issue
|
||||
description: >
|
||||
Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
|
||||
Use when implementing issues or when user says /work-issue.
|
||||
model: haiku
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
### Background Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: gitea
|
||||
description: >
|
||||
View, create, and manage Gitea issues and PRs using tea CLI.
|
||||
Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
|
||||
user-invocable: false
|
||||
---
|
||||
```
|
||||
|
||||
### Read-Only Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: >
|
||||
Automated code review of pull requests for quality, bugs, security, style, and test coverage.
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
```
|
||||
|
||||
### Implementation Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: issue-worker
|
||||
description: >
|
||||
Autonomously implements a single issue in an isolated git worktree.
|
||||
model: haiku
|
||||
skills: gitea, issue-writing, software-architecture
|
||||
---
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Name Validation
|
||||
- Must be lowercase
|
||||
- Must use hyphens (not underscores or spaces)
|
||||
- Cannot contain: `anthropic`, `claude`
|
||||
- Cannot contain XML tags `<`, `>`
|
||||
- Max 64 characters
|
||||
- Must match directory name exactly
|
||||
|
||||
### Description Validation
|
||||
- Cannot be empty
|
||||
- Max 1024 characters
|
||||
- Cannot contain XML tags
|
||||
- Should end with period
|
||||
|
||||
### Model Validation
|
||||
- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
|
||||
- Case-sensitive (must be lowercase)
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
**Bad: Using paths in skills field**
|
||||
```yaml
|
||||
skills: ~/.claude/skills/gitea/SKILL.md # Wrong!
|
||||
```
|
||||
|
||||
**Good: Just skill names**
|
||||
```yaml
|
||||
skills: gitea, issue-writing
|
||||
```
|
||||
|
||||
**Bad: Reserved word in name**
|
||||
```yaml
|
||||
name: claude-helper # Contains "claude"
|
||||
```
|
||||
|
||||
**Good: Descriptive name**
|
||||
```yaml
|
||||
name: code-helper
|
||||
```
|
||||
|
||||
**Bad: Vague description**
|
||||
```yaml
|
||||
description: Helps with stuff
|
||||
```
|
||||
|
||||
**Good: Specific description**
|
||||
```yaml
|
||||
description: >
|
||||
Analyze Excel spreadsheets, create pivot tables, generate charts.
|
||||
Use when analyzing Excel files, spreadsheets, or .xlsx files.
|
||||
```
|
||||
Reference in New Issue
Block a user