creating-instructions

Creating Custom Instructions

Process

Step 1: Plan the Instruction

Before creating, check for overlap and determine scope:

# List existing instructions with patterns
for f in .github/instructions/*.instructions.md; do
  echo "=== $(basename $f) ==="
  grep "applyTo:" "$f"
done

Answer:

1. What file pattern(s) should this apply to?
2. Does this overlap with existing instructions?
3. What are the 3-5 most critical rules?

Decision:

• Exact match exists → Modify existing (see "Modifying" below)
• Partial overlap → Extend existing OR create with distinct scope
• No overlap → Create new

Step 2: Initialize

node .github/skills/creating-instructions/scripts/init_instruction.mjs {name}

# With custom pattern
node .github/skills/creating-instructions/scripts/init_instruction.mjs {name} --apply-to "glob-pattern"

Creates: .github/instructions/{name}.instructions.md with frontmatter and TODO sections.

Naming conventions:

See naming-conventions.md for details.

Step 3: Complete the Instruction

Fill in the generated file:

1. Start with the most critical rule
2. Organize by topic with clear headings
3. Provide concrete code examples
4. Reference related files with Markdown links
5. Document hierarchy if conflicts possible

For format details, see SPECIFICATION.md. For writing guidance, see best-practices.md. For examples, see examples.md.

Step 4: Validate

node .github/skills/creating-instructions/scripts/validate_instruction.mjs .github/instructions/{name}.instructions.md

Manual checks:

• Most critical rule appears first
• Concrete examples provided
• No duplicated content
• Hierarchy documented if needed

Modifying Existing Instructions

Extending:

1. Read existing file to understand scope
2. Add new sections logically
3. Re-run validation

Changing scope:

1. Update applyTo frontmatter
2. Check for new conflicts
3. Update hierarchy documentation

Renaming:

1. Rename file following conventions
2. Search for references: grep -r "{old-name}.instructions.md" .github/
3. Update references
4. Re-validate

Deprecating:

1. Verify no active references
2. If merging, copy unique content to target
3. Delete file

Existing Instructions

Update this table when creating new instructions.

Reference Documentation

Scripts