Turn Your Existing Configs into Reusable SKILL.md Files

You've built the perfect prompt file. It works every time in Cursor, Claude, or your favorite AI tool. The problem? It lives in one folder, tied to one project, useless everywhere else.

Converting existing configs like .cursorrules or CLAUDE.md files into SKILL.md spec format solves this. You get the same behavior, but now it's portable, shareable, and installable across projects.

What makes SKILL.md different

Your current prompt files work, but they're location-dependent. A .cursorrules file only affects that specific directory. Custom system prompts get copy-pasted between projects. SKILL.md files become portable units you can install anywhere.

The conversion isn't just copying text. SKILL.md files include metadata, dependencies, and structured sections that make them work across different AI tools and contexts.

Converting .cursorrules files

Most .cursorrules files contain project-specific instructions mixed with general coding practices. Extract the reusable parts.

Your original .cursorrules might look like this:

You are an expert React developer. Always use TypeScript.
Write clean, functional components. Prefer hooks over classes.
Use Tailwind for styling. Never use inline styles.
This project uses Next.js 14 with app router.

Split this into reusable and project-specific sections. The TypeScript and React preferences become a SKILL.md. The Next.js details stay in your project .cursorrules.

Create react-typescript-expert.md in your skills directory:

# React TypeScript Expert

Expert React development with TypeScript best practices.

## Instructions

You are an expert React developer who writes production-ready TypeScript code.

### Component standards
- Always use TypeScript with strict mode enabled
- Write functional components with proper typing
- Prefer hooks over class components
- Use proper prop interfaces and default values

### Code style
- Use meaningful variable and component names
- Write single-responsibility components
- Extract custom hooks for complex logic
- Include JSDoc comments for public APIs

## Examples

```typescript
interface ButtonProps {
  variant: 'primary' | 'secondary';
  onClick: () => void;
  children: React.ReactNode;
}

const Button: React.FC<ButtonProps> = ({ 
  variant = 'primary', 
  onClick, 
  children 
}) => {
  return (
    <button 
      className={`btn ${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
};

Dependencies

TypeScript 4.9+
React 18+


Your project `.cursorrules` becomes much simpler:

```text
Use the React TypeScript Expert skill for all components.
This project uses Next.js 14 with app router.
Use Tailwind for styling. Config is in tailwind.config.js.

Converting CLAUDE.md files

Many developers maintain CLAUDE.md files with detailed instructions. These often contain multiple skills bundled together.

Break large files into focused skills. A 200-line CLAUDE.md covering API design, database patterns, and testing strategies becomes three separate SKILL.md files.

Take this section from a typical CLAUDE.md:

## API Design
- Use REST principles
- Always return consistent error formats
- Include request IDs for tracing
- Use proper HTTP status codes
- Validate input data

## Error Format
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid email format",
    "request_id": "req_123"
  }
}

This becomes api-design-standards.md:

# API Design Standards

REST API design with consistent error handling and validation.

## Instructions

Design APIs that follow REST principles with predictable error formats.

### Response standards
- Use appropriate HTTP status codes (200, 201, 400, 401, 404, 500)
- Include request IDs in all responses for tracing
- Return consistent error object structure
- Validate all input data before processing

### Error format
Always use this JSON structure for errors:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description",
    "request_id": "req_unique_id",
    "details": {}
  }
}

Common error codes

VALIDATION_FAILED - Input validation errors
RESOURCE_NOT_FOUND - 404 scenarios
UNAUTHORIZED - Authentication required
FORBIDDEN - Insufficient permissions

Examples

// Good: Consistent error response
app.post('/users', (req, res) => {
  if (!req.body.email) {
    return res.status(400).json({
      error: {
        code: 'VALIDATION_FAILED',
        message: 'Email is required',
        request_id: req.id
      }
    });
  }
});


## Converting custom prompts

Personal prompt collections often contain gold mines of specific instructions. Extract the patterns that work repeatedly.

You might have a prompt like: "Write Git commit messages that start with a verb, stay under 50 characters, and explain the why, not the what."

This becomes `git-commit-standards.md`:

```markdown
# Git Commit Standards

Write clear, consistent commit messages following conventional format.

## Instructions

Generate commit messages that follow these rules:

### Format requirements
- Start with imperative verb (Add, Fix, Update, Remove)
- Keep first line under 50 characters
- Use present tense ("Add feature" not "Added feature")
- Capitalize first letter
- No period at the end of subject line

### Content guidelines
- Explain WHY the change was made, not WHAT was changed
- Reference issue numbers when applicable
- Use body for detailed explanation if needed

## Examples

Good commits:
- `Fix memory leak in user session handler`
- `Add email validation to signup form`
- `Update API rate limiting for mobile clients`

Bad commits:
- `fixed bug` (not specific)
- `Updated files` (doesn't explain purpose)
- `WIP` (not descriptive)

## Usage

When writing commits, ask yourself: "If someone reads this in 6 months, will they understand why this change was necessary?"

Handling tool-specific features

Some configs use tool-specific features that don't translate directly. Cursor's @workspace or Claude's artifact generation need adaptation.

Instead of tool-specific commands, write instructions that work across platforms:

## Context awareness

When working on existing code:
- Review related files in the current directory
- Check for existing patterns and conventions
- Maintain consistency with established style
- Reference configuration files when making decisions

This approach works whether someone uses Cursor's workspace awareness or manually provides context.

Testing your converted skills

Install your new SKILL.md files and test them against your original configs. The behavior should be identical or better.

Create a simple test project. Apply your original .cursorrules file and generate some code. Then replace it with your converted skills and generate similar code. Compare the outputs.

If the SKILL.md version produces different results, refine the instructions. Often the issue is missing context that was implicit in the original file.

Making skills discoverable

Once converted, share your skills so others benefit from your hard work. Many developers solve identical problems with slightly different approaches.

Your React TypeScript skill might inspire someone to create a Vue TypeScript variant. Your API standards could become the foundation for GraphQL guidelines.

Good skills get forked, modified, and improved by the community. Your personal .cursorrules file becomes a starting point for dozens of other developers.

The goal isn't perfection on the first try. Convert what works, test it, then iterate based on real usage across different projects.