my-ai-home 0.1.0

Local home base for AI agent skills, MCP servers, profiles, and Claude Code setup

My AI Home

A local control center for Claude Code skills, MCP servers, profiles, and project/global setup.

my-ai-home installs the myai command. Use it when you keep reusable AI-agent capabilities in a personal MY_AI_ROOT workspace and want to install only the relevant skills and MCP servers into each Claude Code project.

It is built for people who maintain many local skills, MCP configs, and project presets, but still want project installs to be explicit, reviewable, and safe.

[!IMPORTANT] The package is currently alpha. The registry format is intentionally small and versioned, but command behavior may still evolve.

Why use it?

• One home for agent capabilities — keep skills, MCP definitions, and profiles in a single MY_AI_ROOT workspace.
• Project-scoped installs — install symlinks into <project>/.claude/skills/ and MCP entries into <project>/.mcp.json.
• Global scope is explicit — use myai global when you really want to manage Claude Code user/global config.
• Profiles for repeatable setup — define curated bundles such as coding, then preview or apply them per project.
• Safe planning flow — inspect planned changes before writing; unmanaged project-owned entries are not overwritten implicitly.
• Agent-friendly registries — YAML registries are the machine source of truth; Markdown manifests remain human documentation.

Table of contents

• Quickstart
• Installation
• Core concepts
• Usage
• Registry format
• Safety boundaries
• Development
• Publishing
• License

Quickstart

Install the CLI, create or migrate a workspace, then manage a project from that project directory.

uv tool install my-ai-home

myai migrate --target ~/my_ai
export MY_AI_ROOT=~/my_ai

myai registry check

cd /path/to/project
myai plan --profile coding
myai apply --profile coding

Run myai with no subcommand in an interactive terminal to open the Textual TUI.

cd /path/to/project
myai

In non-interactive contexts, myai prints a project summary instead.

Installation

From PyPI

uv tool install my-ai-home
myai --help

From source

git clone https://github.com/Cookie-HOO/my-ai-home.git
cd my-ai-home
uv tool install -e .
myai --help

Requirements

• Python >=3.11
• uv for the recommended install and development workflow
• Claude Code if you want the generated .claude/skills/ and .mcp.json project files to be consumed directly

Core concepts

MY_AI_ROOT

MY_AI_ROOT points to your personal AI workflow workspace:

my_ai/
  skills/
    registry.yaml
    custom/
    installed/
    SKILL_MANIFEST.md
  mcps/
    registry.yaml
    MCP_MANIFEST.md
  profiles/
    registry.yaml
  tools/
    TOOL_MANIFEST.md
    EXTERNAL_TOOLS.md

Machine-readable sources of truth:

• skills/registry.yaml
• mcps/registry.yaml
• profiles/registry.yaml

Markdown manifest files are for humans and agents. They are not parsed as the machine source of truth.

Scopes

Command	Scope	Writes to
myai	Current project	<project>/.claude/skills/, <project>/.mcp.json
myai migrate	Bootstrap workspace	Target MY_AI_ROOT skeleton and imported file-backed config where safe
myai global	Claude Code user/global config	Claude Code global/user-scope skills and MCP config

Project mode refuses to run inside ~/.claude so global changes are never inferred from the current directory. Use myai migrate or myai global for that scope.

Managed vs project-owned entries

myai distinguishes entries it manages from entries already owned by a project:

• Managed skill installs are symlinks pointing into MY_AI_ROOT.
• Managed MCP installs include MYAI_* marker env keys injected by myai.
• Existing unmarked MCP entries are treated as project-owned and are not overwritten implicitly.

Usage

Open the project TUI

cd /path/to/project
myai

The TUI lets you:

• choose a profile or custom selection,
• toggle skills and MCP servers,
• review the generated plan,
• apply the plan after confirmation.

Inspect project state

myai doctor

Shows detected skills and MCP servers for the current project, including whether each entry is managed, project-owned, broken, orphaned, or conflicting.

List available registry entries

myai list skills
myai list mcps
myai list profiles

Preview and apply a project profile

myai plan --profile coding
myai apply --profile coding

Use --yes to apply without an interactive confirmation:

myai apply --profile coding --yes

Bootstrap or migrate a workspace

myai migrate --target ~/my_ai --dry-run
myai migrate --target ~/my_ai
export MY_AI_ROOT=~/my_ai

myai migrate creates a workspace skeleton and imports file-backed global skills or global MCP config where safe. It does not delete or mutate old global Claude Code config.

Validate registries

myai registry check

Manage global/user scope explicitly

myai global
myai global doctor
myai global list skills
myai global list mcps
myai global plan --profile coding

Global operations are intentionally separate from project operations.

Command reference

myai [OPTIONS] COMMAND [ARGS]...

Commands:
  doctor    Inspect current project state.
  plan      Preview project changes for a profile.
  apply     Apply project changes for a profile.
  migrate   Create or update a MY_AI_ROOT workspace.
  list      List registry entries.
  registry  Validate registries.
  global    Manage Claude Code global/user scope explicitly.

Common options:

Command	Options
myai plan	--profile, -p
myai apply	--profile, -p, --yes
myai migrate	--target PATH, --dry-run, --yes

Use --help for the full generated help:

myai --help
myai plan --help
myai migrate --help
myai registry --help

Registry format

All registries are YAML files with version: 1.

Skill registry

version: 1
skills:
  readme-writing-polish:
    name: readme-writing-polish
    path: skills/custom/readme-writing-polish
    sourceType: custom
    install:
      type: symlink
    description: README writing and polishing.
    recommendedFor: [coding, docs]
    tags: [readme, writing]
    sensitivity: normal
    status: active

Rules:

• The registry key and name must match.
• path is relative to MY_AI_ROOT.
• The target directory must contain SKILL.md.
• sourceType is custom or installed.
• install.type is currently symlink.
• sensitivity is one of normal, personal, internal, secret-adjacent.
• status is one of active, deprecated, hidden.

MCP registry

version: 1
servers:
  fetch:
    name: fetch
    description: Fetch URL content.
    category: [web]
    recommendedFor: [coding, research]
    tags: [fetch, web]
    status: active
    config:
      type: stdio
      command: uvx
      args:
        - mcp-server-fetch
    requires:
      externalTools: [uv]
      env: []
      auth: []
      files: []
    safety:
      network: true
      opensBrowser: false
      writesFiles: false
      externalService: true
      notes: Accesses external network resources.

Rules:

• The registry key and name must match.
• config is copied into project .mcp.json when installed.
• Do not store tokens, cookies, API keys, passwords, or private env file contents in mcps/registry.yaml.
• MYAI_* env keys are reserved. Do not write them in registry config; myai injects markers only into project installs.

Profile registry

version: 1
profiles:
  coding:
    name: coding
    title: Coding project
    description: Basic Claude Code setup for software projects.
    status: active
    tags: [coding]
    skills:
      required: [brainstorming]
      recommended: [modern-python]
      optional: [readme-writing-polish]
    mcps:
      required: [fetch]
      recommended: []
      optional: [playwright]

Rules:

• The registry key and name must match.
• required and recommended are default selections, not hard policy; users can deselect them in the TUI.
• Profile entries reference existing skill and MCP IDs. They do not copy skill contents or MCP config.

Safety boundaries

myai is designed to avoid surprising project/global changes:

• Project mode only writes .claude/skills/ and .mcp.json in the target project.
• Skills are symlinked into projects; skill contents are not copied.
• Existing project-owned MCP entries are not overwritten implicitly.
• MCP registry entries should reference env vars or env files instead of storing secrets.
• MYAI_* marker env keys are reserved for myai ownership tracking.
• Plugin-provided skills and MCPs remain managed by their plugins.
• myai migrate does not delete or mutate old global Claude Code config.
• Global/user-scope changes require explicit myai global commands.

Development

uv sync --all-groups
uv run myai --help
uv run ruff check .
uv run pytest
uv run ty check src/
uv build

The test suite currently covers registry loading, MCP ownership classification, project planning, and project-owned MCP conflict handling.

Publishing

PyPI Trusted Publishing configuration:

• GitHub repository: Cookie-HOO/my-ai-home
• Workflow: .github/workflows/pypi-publish.yml
• Environment: pypi
• Trigger: GitHub release published, or manual workflow_dispatch

The workflow runs lint, tests, type checks, builds the package, then publishes dist/ with pypa/gh-action-pypi-publish.

License

MIT