Integrate Claude Skill into Project Guidelines

Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).

Usage

/trellis:integrate-skill <skill-name>

Examples:

/trellis:integrate-skill frontend-design
/trellis:integrate-skill mcp-builder

Core Principle

[!] Important: The goal of skill integration is to update development guidelines, not to generate project code directly.

Guidelines content -> Write to .trellis/spec/cli/{target}/doc.md

Code examples -> Place in .trellis/spec/cli/{target}/examples/skills/<skill-name>/

Example files -> Use .template suffix (e.g., component.tsx.template) to avoid IDE errors

Where {target} is frontend or backend, determined by skill type.

Execution Steps

1. Read Skill Content

openskills read <skill-name>

If the skill doesn't exist, prompt user to check available skills:

# Available skills are listed in AGENTS.md under <available_skills>

2. Determine Integration Target

Based on skill type, determine which guidelines to update:

Skill Category	Integration Target
UI/Frontend (`frontend-design`, `web-artifacts-builder`)	`.trellis/spec/cli/frontend/`
Backend/API (`mcp-builder`)	`.trellis/spec/cli/backend/`
Documentation (`doc-coauthoring`, `docx`, `pdf`)	`.trellis/` or create dedicated guidelines
Testing (`webapp-testing`)	`.trellis/spec/cli/frontend/` (E2E)

3. Analyze Skill Content

Extract from the skill:

Core concepts: How the skill works and key concepts
Best practices: Recommended approaches
Code patterns: Reusable code templates
Caveats: Common issues and solutions

4. Execute Integration

4.1 Update Guidelines Document

Add a new section to the corresponding doc.md:

@@@section:skill-<skill-name>
## # <Skill Name> Integration Guide

### Overview
[Core functionality and use cases of the skill]

### Project Adaptation
[How to use this skill in the current project]

### Usage Steps
1. [Step 1]
2. [Step 2]

### Caveats
- [Project-specific constraints]
- [Differences from default behavior]

### Reference Examples
See `examples/skills/<skill-name>/`

@@@/section:skill-<skill-name>

4.2 Create Examples Directory (if code examples exist)

# Directory structure ({target} = frontend or backend)
.trellis/spec/cli/{target}/
|-- doc.md                      # Add skill-related section
|-- index.md                    # Update index
+-- examples/
    +-- skills/
        +-- <skill-name>/
            |-- README.md               # Example documentation
            |-- example-1.ts.template   # Code example (use .template suffix)
            +-- example-2.tsx.template

File naming conventions:

Code files: <name>.<ext>.template (e.g., component.tsx.template)
Config files: <name>.config.template (e.g., tailwind.config.template)
Documentation: README.md (normal suffix)

4.3 Update Index File

Add to the Quick Navigation table in index.md:

| <Skill-related task> | <Section name> | `skill-<skill-name>` |

5. Generate Integration Report

Skill Integration Report: `<skill-name>`

# Overview

Skill description: [Functionality description]
Integration target: .trellis/spec/cli/{target}/

# Tech Stack Compatibility

Skill Requirement	Project Status	Compatibility
[Tech 1]	[Project tech]	[OK]/[!]/[X]

# Integration Locations

Type	Path
Guidelines doc	`.trellis/spec/cli/{target}/doc.md` (section: `skill-<name>`)
Code examples	`.trellis/spec/cli/{target}/examples/skills/<name>/`
Index update	`.trellis/spec/cli/{target}/index.md`

{target} = frontend or backend

# Dependencies (if needed)

# Install required dependencies (adjust for your package manager)
npm install <package>
# or
pnpm add <package>
# or
yarn add <package>

[OK] Completed Changes

Added @@@section:skill-<name> section to doc.md
Added index entry to index.md
Created example files in examples/skills/<name>/
Example files use .template suffix

# Related Guidelines

[Existing related section IDs]

6. Optional: Create Usage Command

If this skill is frequently used, create a shortcut command:

/trellis:create-command use-<skill-name> Use <skill-name> skill following project guidelines

Common Skill Integration Reference

Skill	Integration Target	Examples Directory
`frontend-design`	`cli/frontend`	`examples/skills/frontend-design/`
`mcp-builder`	`cli/backend`	`examples/skills/mcp-builder/`
`webapp-testing`	`cli/frontend`	`examples/skills/webapp-testing/`
`doc-coauthoring`	`.trellis/`	N/A (documentation workflow only)

Example: Integrating `mcp-builder` Skill

Directory Structure

.trellis/spec/cli/backend/
|-- doc.md                           # Add MCP section
|-- index.md                         # Add index entry
+-- examples/
    +-- skills/
        +-- mcp-builder/
            |-- README.md
            |-- server.ts.template
            |-- tools.ts.template
            +-- types.ts.template

New Section in doc.md

@@@section:skill-mcp-builder
## # MCP Server Development Guide

### Overview
Create LLM-callable tool services using MCP (Model Context Protocol).

### Project Adaptation
- Place services in a dedicated directory
- Follow existing TypeScript and type definition conventions
- Use project's logging system

### Reference Examples
See `examples/skills/mcp-builder/`

@@@/section:skill-mcp-builder

integrate-skill