Instruction Creator Skill

Instruction Creator

This skill guides the creation of effective custom instruction files that help GitHub Copilot follow project conventions and domain-specific logic.

Environment Detection

Before executing any skill operations, determine the active environment and set the skills_source path:

Environment Identification

# Detect environment
if os.name == 'nt':  # Windows
    # Could be native Windows or VS Code running in Windows
    skills_source = os.path.expanduser(r'~\.copilot\skills')
elif 'WSL_DISTRO_NAME' in os.environ or os.path.exists('/mnt/c'):
    # Running inside WSL
    skills_source = os.path.expanduser('~/.copilot/skills')
else:
    # Generic Unix/Linux
    skills_source = os.path.expanduser('~/.copilot/skills')

Using skills_source Throughout

Once detected, use skills_source as the base path when referencing skill files:

Skill Path: {skills_source}/<skill-name>/SKILL.md
Script Path: {skills_source}/<skill-name>/scripts/<script>.py
Reference Path: {skills_source}/<skill-name>/references/<file>.md

Workflow

Detect Environment: Determine if running on Windows or WSL and set skills_source.

import os
skills_source = (os.path.expanduser(r'~\.copilot\skills')
                if os.name == 'nt' and 'WSL_DISTRO_NAME' not in os.environ
                else os.path.expanduser('~/.copilot/skills'))

Define Scope: Identify the purpose and the files the instructions should apply to (e.g., **/*.ts).

Initialize: Use the initialization script to create the boilerplate.

# Auto-detect environment
python3 init_instruction.py "my-new-instruction" \
    --description "Description here" \
    --applyTo "**/*.ext"

# Or specify skills path explicitly
python3 init_instruction.py "my-new-instruction" \
    --skills-path "~/.copilot/skills" \
    -o ./instructions

Draft Content: Follow the referenced guidelines to fill in the sections.
Use Templates: Refer to standard templates for structures in your environment.

Semantic Linking: Link to relevant Skills using runtime-resolved paths:

To perform [Task], execute the [Skill Name](SKILL.md) from `{skills_source}/<skill-name>/`.

Validate: Test the instructions with Copilot to ensure they are clear and actionable.

Core Principles

Policy Maker: Instructions define the "What" and "How" (decision logic and standards).
The 4 Sections: Effective instructions include: Overview, Structure, Guidelines, and Resources.
Concise & focused: Avoid fluff; use imperative language. Limit files to ~500 lines.
Actionable: Provide concrete "Good" and "Bad" code examples and clear steps.
Linked: Connect instructions to the skills that execute them and internal automation scripts.

Required Frontmatter

Every instruction file must include YAML frontmatter with the following fields:

---
description: 'Brief description of the instruction purpose and scope'
applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
---

Frontmatter Guidelines

description: Single-quoted string, 1-500 characters, clearly stating the purpose.
applyTo: Glob pattern(s) specifying which files these instructions apply to.
- Single pattern: '**/*.ts'
- Multiple patterns: '**/*.ts, **/*.tsx, **/*.js'
- Specific files: 'src/**/*.py'
- All files: '**'

File Structure

A well-structured instruction file should include these sections as applicable:

Title and Overview: Clear # title and short purpose statement.
Workflow: Step-by-step procedures (the “How”).
Semantic Links: Links to Skills that execute tasks (the “Mechanism”).
Rules & Constraints: Decision logic and boundaries.
Best Practices: Recommended patterns and approaches.
Code Standards: Naming, formatting, style.
Common Patterns: Frequent implementations.
Security: Security considerations (if applicable).
Performance: Optimization guidance (if applicable).
Testing: Testing standards and verification steps (if applicable).

Writing Style

Use clear, concise language.
Write in imperative mood (“Use”, “Implement”, “Avoid”).
Be specific and actionable.
Avoid ambiguous terms like “should”, “might”, “possibly”.
Use bullets and lists for readability.

Examples and Snippets

Provide labeled examples:

### Good Example
```language
// Recommended approach
code example here
```

### Bad Example
```language
// Avoid this pattern
code example here
```

Patterns to Avoid

Overly verbose explanations.
Outdated guidance.
Abstract rules without concrete examples.
Contradictory advice.
Copy-paste from docs without added context.

Runtime Variables

When executing this skill, use these variables to reference paths dynamically:

| Variable | Description | Example (Windows) | Example (WSL) | | --------------- | ----------------------------------- | ----------------------------------- | ----------------------------------- | | skills_source | Base path to personal skills folder | ~\.copilot\skills | ~/.copilot/skills | | skill_path | Path to specific skill | {skills_source}\diataxis\SKILL.md | {skills_source}/diataxis/SKILL.md |

Usage in References

## Workflow
1. Analyze requirements.
2. Execute Diataxis Skill from `{skills_source}/diataxis/SKILL.md`.
3. Validate output.

Usage in Scripts

import os
skills_source = os.path.expanduser(r'~\.copilot\skills') if os.name == 'nt' else os.path.expanduser('~/.copilot/skills')
skill_script = os.path.join(skills_source, 'instruction-creator', 'scripts', 'init_instruction.py')

Validation Checklist

Test with Copilot on real prompts.
Verify code examples compile or run.
Confirm applyTo matches intended files.
Verify skills_source detection works in target environment.

Maintenance

Review instructions when dependencies or frameworks change.
Refresh examples to match current best practices.
Remove deprecated patterns.
Keep glob patterns aligned with project structure.
Update environment detection logic if new platforms are supported.

Resources

Guidelines: Refer to references/guidelines.md in the instruction-creator skill folder.
Templates: Refer to references/templates.md in the instruction-creator skill folder.
Scripts: Use scripts/init_instruction.py from the instruction-creator skill folder.

Note: All references are relative to {skills_source}/instruction-creator/.

Agent Skills: Instruction Creator

Install this agent skill to your local

Skill Files