skillsmith

One command to make your repo agent-ready.

skillsmith gives AI coding assistants the project context they need to work reliably: structure, rules, state files, and reusable skills. It bootstraps a portable .agent/ workspace, wires platform-specific instruction files, and can expose skills over MCP for on-demand use.

Why skillsmith

Without project structure, agents lose context, repeat mistakes, and drift.

With skillsmith, every repo gets:

• A standard agent workspace (.agent/)
• Shared project memory (PROJECT.md, ROADMAP.md, STATE.md)
• Platform-specific instruction files (Claude, Gemini, Cursor, Windsurf, Copilot)
• A skill layer for repeatable workflows and better execution quality
• Optional MCP server for dynamic skill retrieval

Install

pip install skillsmith

For MCP support:

pip install skillsmith[mcp]

60-Second Quick Start

skillsmith init

This scaffolds:

• AGENTS.md
• CLAUDE.md, GEMINI.md
• .cursorrules, .cursor/rules/skillsmith.mdc
• .windsurfrules
• .github/copilot-instructions.md
• .agent/ with state files, guides/plans/workflows, and starter skills

Core Capabilities

1) Project Bootstrapping

skillsmith init
skillsmith init --minimal
skillsmith init --agents-md-only
skillsmith init --all
skillsmith init --category <category>
skillsmith init --tag <tag>

2) Skill Discovery and Management

skillsmith list
skillsmith list --list-categories
skillsmith list --category <category>
skillsmith list --tag <tag>

skillsmith add <skill-name>
skillsmith add <github-directory-url>

skillsmith update
skillsmith update --force

skillsmith lint
skillsmith lint --local
skillsmith lint --spec agentskills

3) Workflow and Health Tooling

skillsmith compose "build a saas mvp"
skillsmith doctor
skillsmith doctor --fix
skillsmith budget

5) Context Management

Save a snapshot of your .agent/ before big changes or long breaks:

skillsmith snapshot                          # save current state
skillsmith snapshot -n "before refactor"    # save with a note
skillsmith snapshot --list                   # list all snapshots
skillsmith snapshot --restore 2026-02-19_10-30-00.zip

Watch for context drift in the background:

skillsmith watch                  # poll every 30s
skillsmith watch --interval 60    # poll every 60s
skillsmith watch --stale-hours 8  # warn after 8h instead of 24h

watch detects:

• Git branch switches → prompts you to update STATE.md
• STATE.md staleness → warns when context is older than N hours
• New or removed skills in .agent/skills/

4) MCP Server

Run via stdio (default):

skillsmith serve

Run via HTTP:

skillsmith serve --transport http --host localhost --port 47731

MCP tools exposed:

• list_skills
• get_skill(name)
• search_skills(query)
• compose_workflow(goal)

Platform Integration

Claude Code

claude mcp add skillsmith -- skillsmith serve

HTTP mode:

claude mcp add --transport http skillsmith http://localhost:47731/mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "skillsmith": {
      "command": "skillsmith",
      "args": ["serve"]
    }
  }
}

6) Troubleshooting & PATH Help

If the skillsmith command is not found after installation, you can always use the universal python module execution:

python -m skillsmith init

Use the doctor command to check for PATH issues and get automatic fix suggestions:

python -m skillsmith doctor

Current Status

• Package version: 0.5.2
• CLI scaffolding and management commands are implemented
• Universal OS compatibility with python -m skillsmith and doctor PATH detection
• CLI scaffolding and management commands are implemented
• Starter lifecycle skills are bundled
• MCP server is available with optional dependency install
• Context management: snapshot and watch commands

Development

Run from source:

PYTHONPATH=src python -m skillsmith.cli --help

License

MIT. See LICENSE.