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:
     markdownCopy

     ---
     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:

  - 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:

# 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:

{
  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