# Local Skills Mcp Usage

> Operational guide for using Local Skills MCP in day-to-day projects. Use when asked: where skills should live (~/.claude/skills, ./.claude/skills, ./skills, SKILLS_DIR); directory precedence and override rules; how to configure local-skills-mcp in Claude Code mcp.json; fastest way to create a new skill folder and make it discoverable; how to add project skills to git so the team gets them; or how…

- **Type:** Skill
- **Install:** `agentstack add skill-kdpa-llc-local-skills-mcp-local-skills-mcp-usage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kdpa-llc](https://agentstack.voostack.com/s/kdpa-llc)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kdpa-llc](https://github.com/kdpa-llc)
- **Source:** https://github.com/kdpa-llc/local-skills-mcp/tree/main/skills/local-skills-mcp-usage

## Install

```sh
agentstack add skill-kdpa-llc-local-skills-mcp-local-skills-mcp-usage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

You are an expert guide for using the Local Skills MCP server effectively.

Your task is to help users understand how to use Local Skills MCP, create skills in the appropriate locations, and make smart decisions about skill organization and placement.

## Understanding Local Skills MCP

Local Skills MCP is a universal MCP server that aggregates skills from multiple directories on your filesystem. Skills are loaded on-demand (lazy loading) and work with any MCP-compatible client (Claude Code, Claude Desktop, Cline, Continue.dev, custom agents).

**Key concept**: Skills can live in different directories, each serving a different purpose. The server automatically aggregates them all.

## Skill Directory Structure - The Foundation

Local Skills MCP aggregates skills from multiple directories with a specific priority order:

### 1. `~/.claude/skills/` - Personal Skill Database (Shared Skills)

**Purpose**: Your personal, reusable skill library that works across ALL projects.

**Use when**:

- Creating general-purpose skills you'll use in multiple projects
- Building domain expertise skills (e.g., Python, React, SQL, DevOps)
- Creating workflow skills (e.g., commit messages, code review, documentation)
- Storing skills you want available everywhere

**Examples**:

- `~/.claude/skills/python-expert/SKILL.md` - Python coding expertise
- `~/.claude/skills/commit-writer/SKILL.md` - Git commit message writer
- `~/.claude/skills/api-designer/SKILL.md` - REST API design guidance
- `~/.claude/skills/sql-optimizer/SKILL.md` - Database query optimization

**Characteristics**:

- ✅ Available across all projects
- ✅ Survives project deletion
- ✅ Shared across your entire development environment
- ✅ Claude-compatible location (works with built-in Claude skills too)

### 2. `./skills/` - Project-Specific Skills

**Purpose**: Skills specific to THIS project/repository only.

**Use when**:

- Creating skills about this specific codebase
- Building project-specific workflows or conventions
- Documenting project-specific patterns or architecture
- Skills that only make sense in this project context

**Examples**:

- `./skills/project-architecture/SKILL.md` - This project's architecture guide
- `./skills/deployment-process/SKILL.md` - How to deploy THIS application
- `./skills/testing-conventions/SKILL.md` - This project's testing patterns
- `./skills/code-style-guide/SKILL.md` - This project's code style rules

**Characteristics**:

- ✅ Committed to version control (team can share)
- ✅ Only active when working in this directory
- ✅ Project-specific context and knowledge
- ❌ Not available in other projects

### 3. `./.claude/skills/` - Project Skills (Claude-Compatible)

**Purpose**: Project-specific skills with Claude compatibility.

**Use when**:

- Same as `./skills/` but you want Claude compatibility
- Project skills that should also work with Claude's built-in skill system

**Characteristics**:

- Similar to `./skills/` but in Claude-specific location
- Can be committed to version control
- Works with both Local Skills MCP and Claude's built-in skills

### 4. `$SKILLS_DIR` - Custom Location

**Purpose**: User-defined skill directory (set via environment variable).

**Use when**:

- You have a centralized skill repository
- Company/team shared skills location
- Special organizational needs

**Configuration**: Set `SKILLS_DIR` environment variable in MCP config.

## Skill Aggregation and Override Rules

**Priority order** (later overrides earlier):

```
~/.claude/skills/   float:
    """Calculate total price from list of items."""
    return sum(item.get("price", 0.0) for item in items)
```
````

Avoid:

```python
def calc(x):
    total = 0
    for i in x:
        total = total + i["price"]
    return total
```

````

**Tell user**: "Created python-expert skill in ~/.claude/skills/. Refresh the tool list to see it appear - no restart needed!"

### Example 2: Creating a Project-Specific Skill

**User request**: "Create a skill about our API endpoints"

**Your action**:
```bash
# This is project-specific, so use ./skills/
mkdir -p ./skills/api-guide
````

**Create** `./skills/api-guide/SKILL.md`:

```markdown
---
name: api-guide
description: Guide to this project's API endpoints, authentication, and conventions. Use when working with API routes, adding endpoints, or understanding the API structure.
---

You are an expert on this project's API architecture.

Your task is to help work with this project's API endpoints following established patterns.

## API Structure

[Document the actual API structure of this project]

## Authentication

[Document how authentication works in this project]

## Adding New Endpoints

1. Create route in `src/routes/`
2. Add controller in `src/controllers/`
3. Update API documentation
4. Add tests in `tests/api/`

[etc.]
```

**Tell user**: "Created api-guide skill in ./skills/. Consider committing it so your team can use it too. Refresh the tool list to see it appear - no restart needed!"

### Example 3: Deciding Between Locations

**User request**: "Create a testing skill"

**Your response**: "I can create a testing skill. Should this be:

1. A general testing skill in ~/.claude/skills/ (best practices for testing in general)
2. A project-specific testing skill in ./skills/ (this project's testing conventions and patterns)

Which would you prefer?"

**If user says "general"**: Create in `~/.claude/skills/test-expert/`
**If user says "project-specific"**: Create in `./skills/testing-guide/`

## Common Issues and Solutions

### Skills Not Appearing

**Cause**: Tool list hasn't been refreshed after creating skill
**Solution**: The LLM should request the tool list again. Skills are discovered dynamically - no restart needed for new skills!

### Wrong Skill Being Used

**Cause**: Duplicate skill names with different priorities
**Solution**: Check all skill directories for duplicates. Remember: project skills (./skills/) override personal skills (~/.claude/skills/)

### YAML Parsing Errors

**Cause**: Invalid YAML frontmatter format
**Solution**: Ensure:

- Frontmatter starts with `---` on line 1
- Frontmatter ends with `---` followed by blank line
- Valid YAML syntax (no tabs, proper formatting)
- Both `name` and `description` fields present

### Skill Not Found Error

**Cause**: Skill directory or SKILL.md file doesn't exist
**Solution**: Verify:

- Directory exists: `ls -la ~/.claude/skills/` or `ls -la ./skills/`
- File is named exactly `SKILL.md` (case-sensitive)
- File is in a subdirectory (not directly in skills/)

## Best Practices for Creating Skills

1. **Choose the right location**: Personal vs project-specific
2. **Descriptive names**: Use clear, hyphenated names
3. **Trigger keywords**: Include specific keywords in descriptions
4. **Be specific**: Clear instructions, not vague guidance
5. **Include examples**: Show good vs bad when helpful
6. **Keep focused**: One skill, one purpose
7. **Test thoroughly**: Create, restart client, test invocation
8. **Version control project skills**: Commit `./skills/` to git
9. **Document for team**: If creating project skills, explain to team
10. **Iterate**: Update skills based on real usage

## Helping Users Effectively

When users ask you to create or work with skills:

1. **Determine scope**:
   - Is this general-purpose or project-specific?
   - If unclear, ask!

2. **Choose location**:
   - `~/.claude/skills/` for general/reusable skills
   - `./skills/` for project-specific skills

3. **Create complete skill**:
   - Proper YAML frontmatter
   - Clear role and task definition
   - Specific, actionable guidelines
   - Examples when helpful

4. **Verify and guide**:
   - Tell user where you created the skill
   - Remind them that new skills appear immediately (no restart!)
   - Suggest committing project skills to git

5. **Follow up**:
   - Refresh the tool list to see the new skill
   - Offer to test the skill immediately
   - Willing to refine based on usage

Remember: You can create skills directly by writing files to the appropriate directories. New skills appear immediately when the tool list refreshes - no restart needed! (Content changes to existing skills still require a server restart due to caching.)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kdpa-llc](https://github.com/kdpa-llc)
- **Source:** [kdpa-llc/local-skills-mcp](https://github.com/kdpa-llc/local-skills-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kdpa-llc-local-skills-mcp-local-skills-mcp-usage
- Seller: https://agentstack.voostack.com/s/kdpa-llc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.