Claude-skill-registry agent-customization

Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md, AGENTS.md). Use for: saving coding preferences; troubleshooting why instructions/skills/agents are ignored or not invoked; configuring applyTo patterns; defining tool restrictions; creating custom agent modes or specialized workflows; packaging domain knowledge; fixing YAML frontmatter syntax.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/agent-customization" ~/.claude/skills/majiayu000-claude-skill-registry-agent-customization-2c0c90 && rm -rf "$T"

manifest: skills/data/agent-customization/SKILL.md

Agent Customization

Decision Flow

Primitive	When to Use
Workspace Instructions	Always-on, applies everywhere in the project
File Instructions	Explicit via `applyTo` patterns, or on-demand via `description`
MCP	Integrates external systems, APIs, or data
Custom Agents	Subagents for context isolation, or multi-stage workflows with tool restrictions
Prompts	Single focused task with parameterized inputs
Skills	On-demand workflow with bundled assets (scripts/templates)

Quick Reference

Consult the reference docs for templates, domain examples, advanced frontmatter options, asset organization, anti-patterns, and creation checklists.

Type	File	Location	Key Field	Reference
Workspace Instructions	`copilot-instructions.md` , `AGENTS.md`	`.github/` or root	N/A (always applies)	Link
File Instructions	`*.instructions.md`	`.github/instructions/`	`applyTo` (explicit), `description` (on-demand)	Link
Prompts	`*.prompt.md`	`.github/prompts/`	`description` (user-invoked)	Link
Custom Agents	`*.agent.md`	`.github/agents/`	`description` (on-demand), `infer` (subagent)	Link
Skills	`SKILL.md`	`.github/skills/<name>/`	`description` (on-demand)	Link

User-level:

{{USER_PROMPTS_FOLDER}}/

(*.prompt.md, *.instructions.md, *.agent.md; not skills) Customizations roam with user's settings sync

Creation Process

If you need to explore or validate patterns in the codebase, use a read-only subagent. If the ask-questions tool is available, use it to interview the user and clarify requirements.

Follow these steps when creating any customization file.

1. Determine Scope

Ask the user where they want the customization:

Workspace: For project-specific, team-shared customizations →
```
.github/
```
folder
User profile: For personal, cross-workspace customizations →
```
{{USER_PROMPTS_FOLDER}}/
```

2. Choose the Right Primitive

Use the Decision Flow above to select the appropriate file type based on the user's need.

3. Create the File

Create the file directly at the appropriate path:

Use the location tables in each reference file
Include required frontmatter as needed
Add the body content following the templates

4. Validate

After creating:

Confirm the file is in the correct location
Verify frontmatter syntax (YAML between
```
---
```
markers)
Check that
```
description
```
is present and meaningful

Edge Cases

Instructions vs Skill? Does this apply to most work, or specific tasks? Most → Instructions. Specific → Skill.

Skill vs Prompt? Multi-step workflow with bundled assets → Skill. Single focused task with inputs → Prompt.

Skill vs Custom Agent? Same capabilities for all steps → Skill. Need context isolation (subagent returns single output) or different tool restrictions per stage → Custom Agent.