*magenta-skills.txt*        Creating Custom Skills           *magenta-skills*

                          MAGENTA.NVIM SKILLS
                      Extending Claude's Capabilities

==============================================================================
CONTENTS                                            *magenta-skills-contents*

    1. Introduction .......................... |magenta-skills-introduction|
    2. Skill Locations ....................... |magenta-skills-locations|
    3. Suppressing Project Skills ............ |magenta-skills-suppress|
    4. Skill Structure ....................... |magenta-skills-structure|
    5. skill.md Format ....................... |magenta-skills-format|
    6. TypeScript Scripts .................... |magenta-skills-scripts|
    7. Recommended Skills .................... |magenta-skills-recommended|
==============================================================================
INTRODUCTION                                   *magenta-skills-introduction*

Skills are custom extensions that empower Claude with project-specific
knowledge and capabilities. Unlike the standard docs tool, skills are
included directly in the system prompt, making them always available during
the agentic workflow.

This guide explains how to create skills for magenta.nvim.

==============================================================================
SKILL LOCATIONS                                   *magenta-skills-locations*

Skills can be placed in several locations, depending on your use case:

Global Skills~
  Location: ~/.magenta/skills/ or ~/.claude/skills/
  Usage: Available across all projects
  Use case: General-purpose skills you want in every project
  Note: Both locations work identically; choose based on preference

Project-Specific Skills~
  Location: .magenta/skills/ (in your project root)
  Usage: Only available in that specific project
  Use case: Project-specific workflows, conventions, or documentation


==============================================================================
SUPPRESSING PROJECT SKILLS                          *magenta-skills-suppress*

When you sync a project's `.magenta/` or `.claude/` directory across machines
(for example via dotfiles, cloud sync, or shared team configs), the project's
skills can override your personal user-level skills with the same name. Use
`suppressProjectSkills` to drop specific project-level skills by name while
keeping your user-level skills intact.

User-level skills directories are those whose paths resolve to a location
inside your home directory (e.g. `~/.magenta/skills`, `~/.claude/skills`).
All other directories — including `.magenta/skills` and `.claude/skills` in
the project root — are treated as project-level.

This option is **user-level only**. Setting it in lua via `setup({...})` or
in `~/.magenta/options.json` works as expected. If you set it in a
project's `.magenta/options.json`, magenta logs a warning and ignores it,
since allowing the project to disable its own suppression would defeat the
purpose.

In lua:~
>lua
    require('magenta').setup({
      suppressProjectSkills = { "plan", "browser" }
    })
<

In `~/.magenta/options.json`:~
>json
    {
      "suppressProjectSkills": ["plan", "browser"]
    }
<

See |magenta-suppressProjectSkills| for the option reference.

==============================================================================
SKILL STRUCTURE                                   *magenta-skills-structure*

Each skill lives in its own subdirectory with a skill.md file:

>
  ~/.magenta/skills/
  └── your-skill-name/
      ├── skill.md          # Required: main skill documentation
      └── scripts/          # Optional: executable scripts
          └── helper.ts     # Optional: TypeScript scripts
<

The skill.md file is the primary documentation and must include YAML
frontmatter with required fields (see |magenta-skills-format|).

Optional scripts/ directory can contain executable TypeScript scripts that
extend the skill's functionality (see |magenta-skills-scripts|).

==============================================================================
SKILL.MD FORMAT                                     *magenta-skills-format*

The skill.md file must include YAML frontmatter with required fields:

>
  ---
  name: your-skill-name
  description: Brief description of what this skill does and when to use it
  ---

  # Your Skill Documentation

  Write your skill documentation here in markdown format.
<

Required Frontmatter Fields~
  name:        Unique identifier for the skill (lowercase with hyphens
               recommended)
  description: Short description that gives Claude hints about the
               content of the skill.md file

The rest of the file is standard markdown documentation that Claude can
reference during the agentic workflow.

System Reminder Blocks~

A skill.md file (and, more generally, any markdown file) may include a
`<system_reminder>...</system_reminder>` block:

>
  # Your Skill Documentation

  <system_reminder>
  Always run the project linter before yielding.
  </system_reminder>
<

When the agent reads such a file with the `get_file` tool, the contents of
the block are folded into the recurring `<system-reminder>` text that is
re-injected on subsequent turns. The same happens while a markdown file
holding such a block is kept as a context file. This keeps the guidance
"alive" across turns rather than burying it once when the file is read.

Notes:
  - Identical reminder text is included only once, whether it came from a
    repeated read or from two different files.
  - These reminders are dropped at compaction: compaction rebuilds an empty
    context, so both transient reads and context-file blocks must be
    re-activated afterwards by reading the file again or re-adding it to
    context.
  - For very large files, `get_file` summarizes/pages the content, so a block
    could be truncated. Reminder-bearing docs (skills) are small, so this is
    not a concern in practice.
  - This parallels the `<system_reminder>` mechanism available in agent
    definition files.

==============================================================================
SCRIPTS                                            *magenta-skills-scripts*

Skills can include executable scripts in a `scripts/` subdirectory.
Scripts are executed by the agent via the `bash_command` tool, so they
are subject to the same sandbox restrictions (see |magenta-permissions|).
Any language works — just document how to invoke the script in your
`skill.md` (e.g., `./script.sh`, `python script.py`, `npx tsx script.ts`).

Example bash script:~
>bash
  #!/usr/bin/env bash
  echo "Running project checks..."
  cd "$(git rev-parse --show-toplevel)"
  npm test
<

Example Python script:~
>python
  #!/usr/bin/env python3
  import json
  with open("package.json") as f:
      data = json.load(f)
  print(f"Project: {data['name']}")
<

Making scripts executable:~
>bash
  chmod +x .magenta/skills/your-skill/scripts/your-script.sh
<

==============================================================================
RECOMMENDED SKILLS                               *magenta-skills-recommended*

Here are some useful skills you can create for your workflow:

Planning Skill~
  A planning skill teaches the agent how to create structured
  implementation plans before starting complex work. This typically
  includes a learning phase (understanding relevant code), an
  architecting phase (designing the solution), and a writing phase
  (documenting the plan to a file).

  Create a planning skill at `~/.magenta/skills/plan/skill.md` with
  your preferred planning methodology. See the magenta.nvim project's
  own `.magenta/skills/plan/skill.md` for an example.

Project Conventions Skill~
  Document your project's coding standards, naming conventions,
  testing patterns, and architectural decisions so the agent follows
  them consistently.

Testing Skill~
  Describe your project's testing framework, how to run tests,
  common test patterns, and fixtures so the agent writes tests that
  match your existing style.

vim:tw=78:ts=8:noet:ft=help:norl:
