docs: create agentic foundations guide and link skill docs to it

[oto-macenauer-absa]

Create "Agentic Foundations" umbrella guide

Problem statement

The repository emphasizes support for multiple agentic tools (GitHub Copilot, Claude, Cursor, and any Agent Skills–compatible client), but current documentation is written from a single-tool perspective. Guidance on skill activation, description writing, and authoring philosophy is scattered and tool-branded (references to "Copilot CLI", "Copilot" as the agent), making it harder for users of other tools to understand that the principles apply universally.

Desired outcome

Create a tool-agnostic "Agentic Foundations" guide documenting the universal principles of skill design and activation. This becomes the source of truth for "what is a skill", "how does it activate", and "how do you write a good description" — applicable to Claude, Copilot, Cursor, and future tools alike.

Scope

This issue covers:

• Creating docs/agentic-foundations.md (~300 lines): universal skill lifecycle, activation mechanics, description and body authoring patterns
• Updating docs/README.md to add a "Foundations" section at the top, surfacing this guide before tool-specific content
• Updating docs/getting-started.md to link to foundations and position tool-specific setup (Copilot CLI install) as one of several entry points
• Updating CONTRIBUTING.md to reference agentic-foundations.md for description/body patterns and cross-link where appropriate
• Updating skills/token-saving/evals/files/pr-description-existing.md to include a note explaining this example applies across all agentic tools, not Copilot-specific scenarios

Out of scope:

• Creating tool-specific guides (e.g., "Getting Started: Claude" or "Getting Started: Cursor") — those are future follow-ups
• Changing skill folder structure or frontmatter schema
• Rewriting skill bodies or descriptions

Assumptions

"Universal" means: activation and authoring patterns that apply identically to Claude, Copilot, Cursor, and any tool implementing the Agent Skills standard. Tool-specific setup (e.g. npx skills add vs. manual symlink) is acknowledged but deferred to tool-specific guides.

Implementation

1. Create docs/agentic-foundations.md

Extract and generalize the universal content from docs/getting-started.md (lines 5–22), CONTRIBUTING.md (lines 88–115), and skills/token-saving/SKILL.md (frontmatter explanation). Structure as:

# Agentic Foundations

Guide to universal principles of AI skill design and activation across all agentic tools.

## What Is a Skill?

[Adapted from docs/getting-started.md lines 5–22, removing Copilot CLI references]
- Definition and purpose
- How skills follow Agent Skills standard
- Comparison to agents and MCP servers (from README FAQ)

## Skill Lifecycle

[New section — generalize discovery/activation/execution from existing docs]
- Discovery: agent loads name + description only
- Activation: description match triggers full SKILL.md load
- Execution: agent follows instructions, optionally loads references or runs scripts

## Writing Skill Descriptions

[Adapt from CONTRIBUTING.md lines 88–130]
- What to include: what it does, when to use it, keywords
- Be explicit about activation language (same content, zero tool branding)
- Length and clarity guidelines
- Examples (existing ones apply universally)

## Writing Skill Bodies

[Adapt from CONTRIBUTING.md lines 132–196]
- Size and progressive disclosure
- Add only what the agent lacks
- Explain the why, not just the what
- Bundle reusable scripts
- Format conventions
- Effective patterns (gotchas, templates, checklists, validation loops)

## What's Not Here

[New callout]
Tool-specific installation, Copilot CLI commands, GitHub-specific workflows belong in tool-specific guides.
See [docs/getting-started.md](./getting-started.md) for Copilot CLI, or consult your tool's documentation.

2. Update docs/README.md

Add a "Foundations" section at the top, before "Setup & Repository Guides":

## Agentic Foundations

| Guide | Description |
|-------|-------------|
| [Agentic Foundations](./agentic-foundations.md) | Universal principles of skill design, activation, and authoring — applicable to Claude, Copilot, Cursor, and any Agent Skills–compatible tool |

Keep the existing tables but update introductory text to reference foundations.

3. Update docs/getting-started.md

Modify the opening to defer universal content to foundations:

Replace lines 1–22 with:

# Getting Started

This guide covers how to install and use skills in your AI-assisted engineering workflow using GitHub Copilot CLI.

For universal principles applicable to any agentic tool (Claude, Cursor, etc.), see [Agentic Foundations](./agentic-foundations.md).

## Prerequisites: Install Copilot CLI
[rest of guide unchanged]

4. Update CONTRIBUTING.md

After the "Skill structure" section (line 30), add:

### Universal authoring guidance

For core principles on writing descriptions and bodies, see [Agentic Foundations](../docs/agentic-foundations.md).
This guide documents GitHub-specific conventions and the PR process for this repository.

No other structural changes needed; keep all guidance as-is.

5. Update skills/token-saving/evals/files/pr-description-existing.md

Prepend:

> This is an example PR description applicable to any platform or agentic tool, not specific to Copilot or GitHub.
> See [Agentic Foundations](../../../docs/agentic-foundations.md) for skill authoring principles.

Acceptance criteria

• docs/agentic-foundations.md created, covering skill lifecycle, description writing, body patterns, with zero tool branding or references to "Copilot", "GitHub Copilot CLI", or tool-specific commands
• All examples in agentic-foundations.md work identically for Claude, Copilot, Cursor (no tool-specific code or setup commands)
• docs/README.md includes "Agentic Foundations" section at the top; all existing content preserved
• docs/getting-started.md updated to position Copilot CLI as one of several entry points; links to agentic-foundations.md
• CONTRIBUTING.md includes forward link to agentic-foundations.md for universal patterns; GitHub-specific PR process content unchanged
• skills/token-saving/evals/files/pr-description-existing.md includes disclaimer note; no other changes
• All docs build without broken links; nav structure tested manually or via a doc-link validator (if one exists)

Testing

No unit or E2E tests apply to documentation changes. Manual verification:

• Read docs/agentic-foundations.md end-to-end; confirm it answers "what is a skill", "how does it activate", and "how do I write one" without tool-specific language
• Follow the forward-link from docs/README.md → agentic-foundations.md; verify nav works
• Check docs/getting-started.md; confirm the Copilot CLI is positioned as tool-specific setup, not universal
• Open CONTRIBUTING.md and verify the link to agentic-foundations.md is reachable and helpful

Notes

This issue prepares the repository for future expansion: once Agentic Foundations is published, new tools can have their own "Getting Started" guide (e.g., "Getting Started with Claude") that links to shared foundations, avoiding doc duplication and keeping the skill authoring guidance in one place.