References

# Add Skill

## Function
Add a new skill (prompt rule) to the CloudBase AI Toolkit project.

## Trigger Condition
When user inputs `/add-skill` or needs to add a new skill/prompt rule

## Workflow

### Step 1: Understand Skill Structure
A skill consists of:
- **Configuration entry** in `doc/prompts/config.yaml`
- **Rule file(s)** in `config/rules/{skill-id}/` directory
- **Generated documentation** in `doc/prompts/{skill-id}.mdx` (auto-generated)
- **Generated prompts data** in `doc/components/prompts.json` (auto-generated from config.yaml)
- **UI component entry** in `doc/components/PromptScenarios.tsx` (manual update)

### Step 2: Create Rule File(s)
Create the rule file(s) in `config/rules/{skill-id}/` directory:

1. **Main rule file**: `config/rules/{skill-id}/rule.md`
   - Must include frontmatter with `name` and `description`
   - Should follow the standard structure:
     ```markdown
     ---
     name: skill-id
     description: Brief description of the skill
     alwaysApply: false
     ---
     
     # Skill Title
     
     Brief description of when to use this skill.
     
     ## When to use this skill
     
     Use this skill when...
     
     ## How to use this skill (for a coding agent)
     
     1. First step
     2. Second step
     ...
     
     ## Core Knowledge
     
     Detailed knowledge and guidelines...
     ```

2. **Optional sub-files**: If the skill is complex, you can split it into multiple files:
   - `rule.md` - Main rule file
   - `{topic}.md` - Sub-topics (e.g., `crud-operations.md`, `pagination.md`)
   - All files in the directory will be included in the generated documentation

### Step 3: Add Configuration to config.yaml
Add a new entry to `doc/prompts/config.yaml`:

```yaml
  - id: skill-id
    title: Skill Title (Chinese)
    description: Skill description (Chinese)
    category: category-id  # auth, database, backend, frontend, or tools
    order: number  # Order within the category
    prompts:
      - "Example prompt 1"
      - "Example prompt 2"
    # Optional: if rule files are in a different directory
    # ruleDir: different-directory-name
```

**Important Notes:**
- `id` must match the directory name in `config/rules/`
- `category` must be one of: `auth`, `database`, `backend`, `frontend`, `tools`
- `order` determines the display order within the category
- `prompts` are example prompts users can try

### Step 4: Generate Documentation and Prompts Data
Run the generation scripts to create the MDX documentation and prompts JSON:

```bash
# Generate MDX documentation from rule files
node scripts/generate-prompts.mjs

# Generate prompts.json from config.yaml (for AIDevelopmentPrompt component)
npm run build:prompts-data
```

This will:
- Generate `doc/prompts/{skill-id}.mdx` from the rule files
- Update `doc/sidebar.json` automatically
- Generate `doc/components/prompts.json` from `config.yaml` (used by `AIDevelopmentPrompt` component)

### Step 5: Update PromptScenarios Component
Manually add the new skill to `doc/components/PromptScenarios.tsx`:

1. Find the appropriate category section
2. Add a new entry following the existing format:

```typescript
{
  id: 'skill-id',
  title: 'Skill Title',
  description: 'Skill description',
  category: 'Category Name (Chinese)',
  docUrl: '/ai/cloudbase-ai-toolkit/prompts/skill-id',
},
```

**Category Mapping:**
- `auth` → `'身份认证'`
- `database` → `'数据库'`
- `backend` → `'后端开发'`
- `frontend` → `'应用集成'`
- `tools` → `'开发工具'`

### Step 6: Verify Generated Files
Check that:
- ✅ `doc/prompts/{skill-id}.mdx` exists and has correct content
- ✅ `doc/sidebar.json` includes the new skill in the correct category
- ✅ `doc/components/prompts.json` includes the new skill with all prompts
- ✅ `doc/components/PromptScenarios.tsx` includes the new skill
- ✅ Rule files are properly formatted with frontmatter

### Step 7: Test the Skill
1. Verify the generated MDX file renders correctly
2. Check that the skill appears in the UI components
3. Test that example prompts work as expected

## Important Notes

### Rule File Best Practices
1. **Frontmatter is required**: Every rule file must have YAML frontmatter
2. **Clear structure**: Follow the standard structure (When to use, How to use, Core Knowledge)
3. **English content**: Rule files should be in English (documentation is auto-generated in Chinese)
4. **Code examples**: Include practical code examples when relevant
5. **Tool references**: Reference specific MCP tools when applicable

### Category Guidelines
- **auth**: Authentication-related skills (login, signup, user management)
- **database**: Database operations (NoSQL, MySQL, data modeling)
- **backend**: Backend services (cloud functions, cloudrun)
- **frontend**: Frontend integration (Web, mini program, UI design)
- **tools**: Development tools and workflows (spec workflow, platform knowledge)

### File Naming Conventions
- Skill ID: lowercase, hyphen-separated (e.g., `cloud-functions`, `auth-web`)
- Rule file: Always `rule.md` for the main file
- Sub-files: Descriptive names (e.g., `crud-operations.md`, `pagination.md`)

## Example

```
/add-skill I need to add a new skill for "Cloud Storage Web SDK"

→ Guide through all 7 steps to add complete skill support
```

## Success Criteria

- [ ] Rule file(s) created in `config/rules/{skill-id}/`
- [ ] Configuration added to `doc/prompts/config.yaml`
- [ ] Documentation generated via `node scripts/generate-prompts.mjs`
- [ ] Prompts data generated via `npm run build:prompts-data`
- [ ] Entry added to `doc/components/PromptScenarios.tsx`
- [ ] Generated MDX file exists and is correct
- [ ] Generated `prompts.json` includes the new skill
- [ ] Sidebar updated automatically
- [ ] All files verified and tested