Skip to content

Commit d9bb1c1

Browse files
AndyLiner13AndyLiner13
committed
Multi-Repo Consolidation
1 parent 35d8056 commit d9bb1c1

212 files changed

Lines changed: 31583 additions & 376 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.copilotignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
documentation/archive/
2+
.devtools/
3+
backups/
4+
test-workspace/
5+
tests/

‎.devtoolsignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Files/folders ignored by vscode-devtools extension change detection.
2+
# Syntax is similar to .gitignore and supports:
3+
# - * and ** globs
4+
# - ! negation (re-include)
5+
# - trailing / for directories
6+
7+
# Build output
8+
out/
9+
build/
10+
11+
# Packaging artifacts
12+
*.vsix
13+
14+
# Optional: ignore generated docs or notes
15+
# docs/generated/
16+
# .devtools/

‎.github/copilot-instructions.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Instructions
2+
3+
Use the #tool:vscode/askQuestions tool often. Even for simple yes or no questions. If you want to ask how we should proceed, or if we should continue, please use the #tool:vscode/askQuestions tool.
4+
5+
## Rules for TypeScript
6+
7+
- Do not use `any` type.
8+
- Do not use `as` keyword for type casting.
9+
- Do not use `!` operator for type assertion.
10+
- Do not use `// @ts-ignore` comments.
11+
- Do not use `// @ts-nocheck` comments.
12+
- Do not use `// @ts-expect-error` comments.
13+
- Prefer `for..of` instead of `forEach`.
14+
15+
## CRITICAL: No VS Code Proposed APIs
16+
17+
- DO NOT use any VS Code proposed APIs anywhere in the codebase.
18+
- DO NOT add `enabledApiProposals` to any `package.json`.
19+
- DO NOT use the `--enable-proposed-api` CLI flag.
20+
- DO NOT use APIs like `findTextInFiles`, `onDidWriteTerminalData`, or any other proposed API.
21+
- We have NO access to proposed APIs. Using them causes the extension to crash into Safe Mode.
22+
- If a feature requires a proposed API, find an alternative using stable APIs only.
23+
24+
## CRITICAL: Hot Reloading — DO NOT Manually Rebuild
25+
26+
- DO NOT manually run build, compile, install, reinstall, or reload commands.
27+
- DO NOT ask the user to rebuild, reinstall, or reload anything.
28+
- DO NOT run `npm run compile`, `npm run build`, or `ext:reinstall` tasks manually.
29+
- EVERYTHING HAS HOT RELOADING BUILT IN.
30+
- The MCP server automatically detects source changes and rebuilds on the next tool call.
31+
- The Extension Development Host automatically picks up changes.
32+
- Just TEST THE TOOLS DIRECTLY after making code changes.
33+
- If tools aren't available yet, call any MCP tool — it will auto-reload and then work.
34+
- Get straight to testing. Skip all rebuild/reinstall steps. It's all automatic.
35+
36+
ASK QUESTIONS AS OFTEN AS YOU POSSIBLY CAN. DO NOT MAKE ANY ASSUMPTIONS ABOUT THE USERS INTENT OR PREFERENCES. IF THE USER HAS NOT EXPLICITLY PROVIDED CONSENT TO A CHANGE, DO NO PROCEED WITHOUT ASKING FIRST VIA THE #tool:vscode/askQuestions TOOL.

‎.github/instructions/agent-skills.instructions.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
3+
applyTo: '**/.github/skills/**/SKILL.md, **/.claude/skills/**/SKILL.md'
4+
---
5+
6+
# Agent Skills File Guidelines
7+
8+
Instructions for creating effective and portable Agent Skills that enhance GitHub Copilot with specialized capabilities, workflows, and bundled resources.
9+
10+
## What Are Agent Skills?
11+
12+
Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Unlike custom instructions (which define coding standards), skills enable task-specific workflows that can include scripts, examples, templates, and reference data.
13+
14+
Key characteristics:
15+
- **Portable**: Works across VS Code, Copilot CLI, and Copilot coding agent
16+
- **Progressive loading**: Only loaded when relevant to the user's request
17+
- **Resource-bundled**: Can include scripts, templates, examples alongside instructions
18+
- **On-demand**: Activated automatically based on prompt relevance
19+
20+
## Directory Structure
21+
22+
Skills are stored in specific locations:
23+
24+
| Location | Scope | Recommendation |
25+
|----------|-------|----------------|
26+
| `.github/skills/<skill-name>/` | Project/repository | Recommended for project skills |
27+
| `.claude/skills/<skill-name>/` | Project/repository | Legacy, for backward compatibility |
28+
| `~/.github/skills/<skill-name>/` | Personal (user-wide) | Recommended for personal skills |
29+
| `~/.claude/skills/<skill-name>/` | Personal (user-wide) | Legacy, for backward compatibility |
30+
31+
Each skill **must** have its own subdirectory containing at minimum a `SKILL.md` file.
32+
33+
## Required SKILL.md Format
34+
35+
### Frontmatter (Required)
36+
37+
```yaml
38+
---
39+
name: webapp-testing
40+
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
41+
license: Complete terms in LICENSE.txt
42+
---
43+
```
44+
45+
| Field | Required | Constraints |
46+
|-------|----------|-------------|
47+
| `name` | Yes | Lowercase, hyphens for spaces, max 64 characters (e.g., `webapp-testing`) |
48+
| `description` | Yes | Clear description of capabilities AND use cases, max 1024 characters |
49+
| `license` | No | Reference to LICENSE.txt (e.g., `Complete terms in LICENSE.txt`) or SPDX identifier |
50+
51+
### Description Best Practices
52+
53+
**CRITICAL**: The `description` field is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY the `name` and `description` to decide whether to load a skill. If your description is vague, the skill will never be activated.
54+
55+
**What to include in description:**
56+
1. **WHAT** the skill does (capabilities)
57+
2. **WHEN** to use it (specific triggers, scenarios, file types, or user requests)
58+
3. **Keywords** that users might mention in their prompts
59+
60+
**Good description:**
61+
```yaml
62+
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
63+
```
64+
65+
**Poor description:**
66+
```yaml
67+
description: Web testing helpers
68+
```
69+
70+
The poor description fails because:
71+
- No specific triggers (when should Copilot load this?)
72+
- No keywords (what user prompts would match?)
73+
- No capabilities (what can it actually do?)
74+
75+
### Body Content
76+
77+
The body contains detailed instructions that Copilot loads AFTER the skill is activated. Recommended sections:
78+
79+
| Section | Purpose |
80+
|---------|---------|
81+
| `# Title` | Brief overview of what this skill enables |
82+
| `## When to Use This Skill` | List of scenarios (reinforces description triggers) |
83+
| `## Prerequisites` | Required tools, dependencies, environment setup |
84+
| `## Step-by-Step Workflows` | Numbered steps for common tasks |
85+
| `## Troubleshooting` | Common issues and solutions table |
86+
| `## References` | Links to bundled docs or external resources |
87+
88+
## Bundling Resources
89+
90+
Skills can include additional files that Copilot accesses on-demand:
91+
92+
### Supported Resource Types
93+
94+
| Folder | Purpose | Loaded into Context? | Example Files |
95+
|--------|---------|---------------------|---------------|
96+
| `scripts/` | Executable automation that performs specific operations | When executed | `helper.py`, `validate.sh`, `build.ts` |
97+
| `references/` | Documentation the AI agent reads to inform decisions | Yes, when referenced | `api_reference.md`, `schema.md`, `workflow_guide.md` |
98+
| `assets/` | **Static files used AS-IS** in output (not modified by the AI agent) | No | `logo.png`, `brand-template.pptx`, `custom-font.ttf` |
99+
| `templates/` | **Starter code/scaffolds that the AI agent MODIFIES** and builds upon | Yes, when referenced | `viewer.html` (insert algorithm), `hello-world/` (extend) |
100+
101+
### Directory Structure Example
102+
103+
```
104+
.github/skills/my-skill/
105+
├── SKILL.md # Required: Main instructions
106+
├── LICENSE.txt # Recommended: License terms (Apache 2.0 typical)
107+
├── scripts/ # Optional: Executable automation
108+
│ ├── helper.py # Python script
109+
│ └── helper.ps1 # PowerShell script
110+
├── references/ # Optional: Documentation loaded into context
111+
│ ├── api_reference.md
112+
│ ├── workflow-setup.md # Detailed workflow (>5 steps)
113+
│ └── workflow-deployment.md
114+
├── assets/ # Optional: Static files used AS-IS in output
115+
│ ├── baseline.png # Reference image for comparison
116+
│ └── report-template.html
117+
└── templates/ # Optional: Starter code the AI agent modifies
118+
├── scaffold.py # Code scaffold the AI agent customizes
119+
└── config.template # Config template the AI agent fills in
120+
```
121+
122+
> **LICENSE.txt**: When creating a skill, download the Apache 2.0 license text from https://www.apache.org/licenses/LICENSE-2.0.txt and save as `LICENSE.txt`. Update the copyright year and owner in the appendix section.
123+
124+
### Assets vs Templates: Key Distinction
125+
126+
**Assets** are static resources **consumed unchanged** in the output:
127+
- A `logo.png` that gets embedded into a generated document
128+
- A `report-template.html` copied as output format
129+
- A `custom-font.ttf` applied to text rendering
130+
131+
**Templates** are starter code/scaffolds that **the AI agent actively modifies**:
132+
- A `scaffold.py` where the AI agent inserts logic
133+
- A `config.template` where the AI agent fills in values based on user requirements
134+
- A `hello-world/` project directory that the AI agent extends with new features
135+
136+
**Rule of thumb**: If the AI agent reads and builds upon the file content → `templates/`. If the file is used as-is in output → `assets/`.
137+
138+
### Referencing Resources in SKILL.md
139+
140+
Use relative paths to reference files within the skill directory:
141+
142+
```markdown
143+
## Available Scripts
144+
145+
Run the [helper script](./scripts/helper.py) to automate common tasks.
146+
147+
See [API reference](./references/api_reference.md) for detailed documentation.
148+
149+
Use the [scaffold](./templates/scaffold.py) as a starting point.
150+
```
151+
152+
## Progressive Loading Architecture
153+
154+
Skills use three-level loading for efficiency:
155+
156+
| Level | What Loads | When |
157+
|-------|------------|------|
158+
| 1. Discovery | `name` and `description` only | Always (lightweight metadata) |
159+
| 2. Instructions | Full `SKILL.md` body | When request matches description |
160+
| 3. Resources | Scripts, examples, docs | Only when Copilot references them |
161+
162+
This means:
163+
- Install many skills without consuming context
164+
- Only relevant content loads per task
165+
- Resources don't load until explicitly needed
166+
167+
## Content Guidelines
168+
169+
### Writing Style
170+
171+
- Use imperative mood: "Run", "Create", "Configure" (not "You should run")
172+
- Be specific and actionable
173+
- Include exact commands with parameters
174+
- Show expected outputs where helpful
175+
- Keep sections focused and scannable
176+
177+
### Script Requirements
178+
179+
When including scripts, prefer cross-platform languages:
180+
181+
| Language | Use Case |
182+
|----------|----------|
183+
| Python | Complex automation, data processing |
184+
| pwsh | PowerShell Core scripting |
185+
| Node.js | JavaScript-based tooling |
186+
| Bash/Shell | Simple automation tasks |
187+
188+
Best practices:
189+
- Include help/usage documentation (`--help` flag)
190+
- Handle errors gracefully with clear messages
191+
- Avoid storing credentials or secrets
192+
- Use relative paths where possible
193+
194+
### When to Bundle Scripts
195+
196+
Include scripts in your skill when:
197+
- The same code would be rewritten repeatedly by the agent
198+
- Deterministic reliability is critical (e.g., file manipulation, API calls)
199+
- Complex logic benefits from being pre-tested rather than generated each time
200+
- The operation has a self-contained purpose that can evolve independently
201+
- Testability matters — scripts can be unit tested and validated
202+
- Predictable behavior is preferred over dynamic generation
203+
204+
Scripts enable evolution: even simple operations benefit from being implemented as scripts when they may grow in complexity, need consistent behavior across invocations, or require future extensibility.
205+
206+
### Security Considerations
207+
208+
- Scripts rely on existing credential helpers (no credential storage)
209+
- Include `--force` flags only for destructive operations
210+
- Warn users before irreversible actions
211+
- Document any network operations or external calls
212+
213+
## Common Patterns
214+
215+
### Parameter Table Pattern
216+
217+
Document parameters clearly:
218+
219+
```markdown
220+
| Parameter | Required | Default | Description |
221+
|-----------|----------|---------|-------------|
222+
| `--input` | Yes | - | Input file or URL to process |
223+
| `--action` | Yes | - | Action to perform |
224+
| `--verbose` | No | `false` | Enable verbose output |
225+
```
226+
227+
## Validation Checklist
228+
229+
Before publishing a skill:
230+
231+
- [ ] `SKILL.md` has valid frontmatter with `name` and `description`
232+
- [ ] `name` is lowercase with hyphens, ≤64 characters
233+
- [ ] `description` clearly states **WHAT** it does, **WHEN** to use it, and relevant **KEYWORDS**
234+
- [ ] Body includes when to use, prerequisites, and step-by-step workflows
235+
- [ ] SKILL.md body kept under 500 lines (split large content into `references/` folder)
236+
- [ ] Large workflows (>5 steps) split into `references/` folder with clear links from SKILL.md
237+
- [ ] Scripts include help documentation and error handling
238+
- [ ] Relative paths used for all resource references
239+
- [ ] No hardcoded credentials or secrets
240+
241+
## Workflow Execution Pattern
242+
243+
When executing multi-step workflows, create a TODO list where each step references the relevant documentation:
244+
245+
```markdown
246+
## TODO
247+
- [ ] Step 1: Configure environment - see [workflow-setup.md](./references/workflow-setup.md#environment)
248+
- [ ] Step 2: Build project - see [workflow-setup.md](./references/workflow-setup.md#build)
249+
- [ ] Step 3: Deploy to staging - see [workflow-deployment.md](./references/workflow-deployment.md#staging)
250+
- [ ] Step 4: Run validation - see [workflow-deployment.md](./references/workflow-deployment.md#validation)
251+
- [ ] Step 5: Deploy to production - see [workflow-deployment.md](./references/workflow-deployment.md#production)
252+
```
253+
254+
This ensures traceability and allows resuming workflows if interrupted.
255+
256+
## Related Resources
257+
258+
- [Agent Skills Specification](https://agentskills.io/)
259+
- [VS Code Agent Skills Documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
260+
- [Reference Skills Repository](https://github.com/anthropics/skills)
261+
- [Awesome Copilot Skills](https://github.com/github/awesome-copilot/blob/main/docs/README.skills.md)

0 commit comments

Comments
 (0)