CLAUDE.md — Project Rules

Repo Structure

Demo Scripts

Demo scripts live at tools/scripts/<demo-name>/<demo-name>.demo. The [var: KEY = value] declarations inside .demo files are defaults only — never edit a .demo file to set a site URL. Site-specific values go in tools/demo.vars.json under overrides["<demo-name>"]:

"overrides": {
  "21-knowledge-base": {
    "SITE": "https://microsoft.sharepoint-df.com/sites/KnowledgeBaseDemo/"
  }
}

The runner merges demo.vars.json overrides on top of the script's [var:] defaults at load time, so the .demo file stays as a site-agnostic template with CONFIGURE_ME placeholders.

The SharePoint agent site context file must be named SHAREPOINT.md — any other name is ignored. Upload it to the AgentAssets library root (not inside Skills/).

Skills

Follow the agentskills.io specification

Skills follow the agentskills.io specification. Each skill is a directory inside Skills/ containing a SKILL.md file:

Skills/
└── skill-name/
    └── SKILL.md          # Required

The directory name must exactly match the name field in the frontmatter. For example, a skill with name: copy-editing must live at Skills/copy-editing/SKILL.md.

SharePoint skills cannot write code

Skills in this repo run in SharePoint, which does not support code execution. Skills must be written entirely in prose and Markdown — no code blocks containing executable code, no scripts, no shell commands, no pseudocode intended for execution.

Required frontmatter

Every SKILL.md must include valid YAML frontmatter with at minimum these two fields:

---
name: skill-name-here
description: Third-person description of what the skill does and when to use it.
---

Frontmatter rules (enforced by the platform):

• name: must match the parent directory name exactly. Lowercase letters, numbers, and hyphens only — no spaces, no uppercase, no consecutive hyphens, max 64 characters. Must not start or end with a hyphen.
• description: non-empty, max 1024 characters, written in third person ("Processes..." not "I can..." or "You can use this to..."), no XML tags. Include both what the skill does and the trigger conditions that should activate it.

Optional frontmatter fields: license, compatibility, metadata, allowed-tools — see the spec for details.

Follow the official best practices guide

Before creating or editing a skill, consult the official authoring guide: https://agentskills.io/specification

Key points:

• Keep SKILL.md body under 500 lines
• Descriptions must include what the skill does AND when to use it
• Be concise — only add context Claude doesn't already have
• Use consistent terminology throughout
• Avoid time-sensitive information
• Use gerund form for skill names where possible (copy-editing, not copy-editor)