john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

copilot instructions

Browse Source
This commit is contained in:
John Lancaster
2026-06-19 01:15:27 -05:00
parent be9551c76e
commit ef3255544f
8 changed files with 345 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/securing.md
+139
View File
@@ -0,0 +1,139 @@
---
icon: lucide/shield-check
---
# Securing Remote Access
## Context
This project exposes two related surfaces from the same runtime:
1. a static documentation site under `/docs`
2. a Streamable HTTP MCP endpoint under `/mcp`
The same Markdown content backs both surfaces. For the current project shape, the MCP server is resource-first and primarily exposes public skill and documentation text. It is not intended to expose secrets, private data, shell access, filesystem access, or tools with side effects.
The expected deployment path is:
```text
Public internet
-> Cloudflare Tunnel
-> Caddy
-> personal-mcp container
```
## Decision
For the current use case, heavy application-level authentication is not required.
The recommended posture is:
1. Keep the service behind Cloudflare Tunnel and Caddy.
2. Do not expose the container port directly to the public internet.
3. Treat everything exposed through MCP as publishable public documentation.
4. Add stronger authentication only if the MCP surface later includes sensitive content or tools with meaningful side effects.
This keeps the deployment simple while preserving a clear upgrade path.
## Tradeoffs
### Leaving `/mcp` Public
This is acceptable if `/mcp` exposes only the same public Markdown already available through `/docs`.
Benefits:
1. lowest operational friction
2. fewer compatibility issues with MCP clients
3. no need to implement OAuth, mTLS, JWT validation, or custom auth middleware
4. consistent with the project assumption that documentation content is public
Risks:
1. random scraping, probing, or fuzzing of a machine endpoint
2. possible bandwidth or CPU nuisance traffic
3. accidental future exposure if new tools or private resources are added
4. less control over who can use the MCP endpoint
### Protecting `/mcp` With Cloudflare Access
Cloudflare Access can add a lightweight gate using GitHub, Google, one-time PIN, or service tokens.
Benefits:
1. reduces random internet traffic
2. requires little app code
3. works well for a small trusted team
4. provides logs and centralized access control
Costs:
1. browser-based login may not work with all MCP clients
2. non-browser MCP clients may need Cloudflare Access service tokens
3. adds operational configuration for a low-sensitivity endpoint
### Using mTLS
mTLS is useful when both client and server environments are tightly controlled.
Benefits:
1. strong client identity
2. good fit for service-to-service or private infrastructure
3. can be used between Cloudflare, Caddy, and the backend if desired
Costs:
1. harder certificate provisioning and rotation
2. weaker compatibility with normal MCP clients
3. unnecessary for public documentation-only content
For this project, mTLS is not the primary recommendation.
## Practical Recommendation
Use a simple public-docs posture unless the endpoint changes.
Recommended current setup:
```text
/docs public
/mcp public or lightly protected
```
If `/mcp` remains public, add only basic operational safeguards:
1. keep Cloudflare Tunnel and Caddy in front
2. avoid publishing `8765` directly
3. enable Cloudflare or Caddy rate limiting if traffic becomes noisy
4. monitor logs for unusual request volume
5. document that MCP resources must remain safe to publish
A slightly stricter setup is also reasonable:
```text
/docs public
/mcp Cloudflare Access or service token
```
This is the best option if the team wants to reduce drive-by MCP traffic without adding auth code to the application.
## Upgrade Trigger
Add real authentication before introducing any MCP capability that can:
1. read non-public files
2. access private notes or credentials
3. call upstream APIs
4. mutate data
5. run commands
6. expose environment details
7. perform expensive computation
At that point, prefer edge-level authentication first, such as Cloudflare Access, and consider proper OAuth 2.1 resource-server behavior only if broad public MCP client interoperability becomes a goal.
## Security Invariant
Everything exposed by the MCP server must be safe to publish publicly.
If that invariant stops being true, `/mcp` should be protected before the new capability is deployed.
docs/skills/copilot-customization/SKILL.md
+78
View File
@@ -0,0 +1,78 @@
---
name: copilot-customization
description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
argument-hint: 'What Copilot behavior are you customizing, and should it be workspace-scoped, personal, or exposed as an MCP skill resource?'
---
# Copilot Customization
Use this skill when a task is about changing how GitHub Copilot or VS Code agents behave through customization files or MCP-backed skill resources.
## When to Use
- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
- Creating prompt files, custom agents, hooks, or Agent Skills.
- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
- Debugging why a customization is not discovered, loaded, or invoked.
- Adding a new documentation-backed skill to this `personal-mcp` repository.
## Start With The Decision
Choose the smallest customization that matches the desired behavior:
1. Use always-on instructions for project-wide coding standards, architecture decisions, security rules, and documentation standards that should apply to most requests.
2. Use file-based instructions for conventions that only apply to matching files, folders, languages, frameworks, or documentation types.
3. Use prompt files for reusable slash commands that package a single recurring prompt.
4. Use Agent Skills for portable, task-specific workflows that may include references, scripts, examples, or templates.
5. Use custom agents for specialized personas, tool restrictions, model choices, or role-specific workflows.
6. Use hooks when a deterministic lifecycle action must enforce a policy, run a command, or block unsafe behavior.
7. Use MCP servers when the agent needs live external tools, structured resources, or discoverable data beyond static instruction files.
8. Use agent plugins when several related customizations should ship together as an installable package.
If the request is ambiguous, ask only for the missing axis that changes the file type: scope, trigger, expected output, required tools, or whether it must be portable beyond VS Code.
## Research Map
Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
## Workspace Customization Workflow
1. Identify the customization primitive and scope.
2. Check existing files before creating a new one.
3. Keep the description or frontmatter trigger specific and keyword-rich.
4. Keep instructions concise, focused, and self-contained.
5. Add examples only when they clarify a non-obvious convention.
6. For `*.instructions.md`, set `applyTo` only when automatic file matching is intended.
7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
## Repo Integration Workflow
When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
2. Create authored docs under `docs/skills/<slug>/SKILL.md`, with optional one-level `references/` files.
3. Choose consistent names: docs slug and resource id use kebab-case; Python namespace uses snake_case.
4. Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
5. Expose only `resource://skills/<skill-id>/document` from the per-skill server.
6. Put discovery metadata in `metadata.yaml`, including `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`.
7. Mount the skill server in `src/personal_mcp/mcp.py` using the Python namespace.
8. Validate with the document loader and `uv run zensical build`.
Keep per-skill servers resource-only. Catalog-level discovery is the only place for thin fallback discovery tools.
## Quality Checks
Before finishing:
1. Confirm the customization file is in a supported location for its intended scope.
2. Confirm required frontmatter fields are present and valid.
3. Confirm names match directory names where VS Code requires it.
4. Confirm descriptions include the phrases users are likely to ask for.
5. Confirm extra skill resources are linked from `SKILL.md`.
6. Confirm repo skill metadata exposes the correct `resource://skills/<skill-id>/document` capability.
7. State any remaining ambiguity or user choice, such as personal vs workspace scope.
## Output Contract
Return the concrete customization created or changed, where it lives, how to invoke or trigger it, and any validation performed.
docs/skills/copilot-customization/references/vscode-customization.md
+82
View File
@@ -0,0 +1,82 @@
# VS Code Copilot Customization References
Use these notes as a source map before creating or debugging Copilot customizations.
## Official Sources
- Customization overview: https://code.visualstudio.com/docs/copilot/customization/overview
- Custom instructions: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
- Agent skills: https://code.visualstudio.com/docs/copilot/customization/agent-skills
- Prompt files: https://code.visualstudio.com/docs/copilot/customization/prompt-files
- Custom agents: https://code.visualstudio.com/docs/copilot/customization/custom-agents
- MCP servers: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
- Hooks: https://code.visualstudio.com/docs/copilot/customization/hooks
## Customization Types
- Instructions describe standards and conventions that apply to every request or to matching files.
- Prompt files save reusable slash-command prompts for recurring tasks.
- Agent Skills package reusable workflows, scripts, examples, and resources that load on demand.
- Custom agents define specialized personas, tool access, model choices, and role-specific workflows.
- MCP servers connect the agent to external tools, resources, and data.
- Hooks run deterministic actions at defined lifecycle points.
- Agent plugins bundle related customization types into an installable package.
## Instructions
Use `.github/copilot-instructions.md` for workspace-wide rules that should be included in every chat request. Use `AGENTS.md` when multiple agents should share the same repository guidance, or when nested agent guidance is useful. Use `CLAUDE.md` for Claude-compatible instruction sharing.
Use `.github/instructions/**/*.instructions.md` for file-based or task-specific rules. Supported frontmatter fields include:
```yaml
---
name: Documentation Standards
description: Rules for documentation writing tasks
applyTo: '**/*.md'
---
```
`applyTo` is a workspace-relative glob. If it is omitted, the instruction file can still be manually attached but does not automatically apply by file match.
## Agent Skills
Skills live in a directory whose name must match the `name` field in `SKILL.md`. VS Code supports project skills in `.github/skills/`, `.claude/skills/`, and `.agents/skills/`, and personal skills under user-level skill folders.
Required skill frontmatter:
```yaml
---
name: skill-name
description: Description of what the skill does and when to use it.
---
```
Useful optional fields:
- `argument-hint`: shown when invoking the skill as a slash command.
- `user-invocable`: controls whether it appears in the slash menu.
- `disable-model-invocation`: controls whether the model can auto-load it.
- `context`: can use `fork` for a separate subagent context when supported.
Skills load progressively: discovery reads frontmatter, instruction loading reads `SKILL.md`, and extra resources load only when linked from the skill document.
## Priority And Discovery
When multiple instruction sources apply, personal instructions have higher priority than repository instructions, and repository instructions have higher priority than organization instructions. If multiple instruction files exist, VS Code combines them; do not rely on ordering between instruction files.
For monorepos, `chat.useCustomizationsInParentRepositories` can enable discovery from a trusted parent repository root. Skill locations can also be configured with `chat.agentSkillsLocations`, and instruction locations with `chat.instructionsFilesLocations`.
## Troubleshooting
If a customization is not applied:
1. Confirm the file is in a supported location.
2. Confirm frontmatter is valid YAML.
3. Confirm skill `name` matches the parent directory.
4. Confirm `applyTo` matches the file path when using `*.instructions.md`.
5. Confirm relevant settings are enabled, such as instruction inclusion, referenced instruction inclusion, or AGENTS/CLAUDE support.
6. Use the Chat customization diagnostics view or Agent Debug Logs to inspect what VS Code loaded.
## Writing Effective Instructions
Keep instructions short, self-contained, and focused on non-obvious rules. Include the reason for a rule when it helps with edge cases. Prefer concrete examples over abstract preferences. Split unrelated rules into separate targeted files when they have different triggers.