github-md-template-fidelity

Files (3)

• SKILL.md
• validate_github_md.cpython-314.pyc · __pycache__/
• validate_github_md.py

SKILL.md (first lines)

# GitHub MD Template Fidelity Skill

This skill enforces **100% template fidelity** for all GitHub markdown document generation. It must be invoked for any task that creates or revises these files.

## Invocation Protocol

When generating or revising any of these files, the agent MUST:
1. Read this skill file first
2. Read the corresponding template AND rules files
3. Execute the full validation pipeline before output

## Target Files & Required Pairs

| Target | Template | Rules | Fidelity |
|--------|----------|-------|----------|
| README.md | `prompts/instructions/github/github.readme.template.instructions.md` | `prompts/instructions/github/github.readme.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| ARCHITECTURE.md | `prompts/instructions/github/github.architecture.template.instructions.md` | `prompts/instructions/github/github.architecture.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| CONTRIBUTING.md | `prompts/instructions/github/github.contributing.template.instructions.md` | `prompts/instructions/github/github.contributing.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| CODE_OF_CONDUCT.md | `prompts/instructions/github/github.code-of-conduct.template.instructions.md` | `prompts/instructions/github/github.code-of-conduct.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| SECURITY.md | `prompts/instructions/github/github.security.template.instructions.md` | `prompts/instructions/github/github.security.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| PRIVACY.md | `prompts/instructions/github/github.privacy.template.instructions.md` | `prompts/instructions/github/github.privacy.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |
| ROADMAP.md | `prompts/instructions/github/github.roadmap.template.instructions.md` | `prompts/instructions/github/github.roadmap.rules.instructions.md` | `prompts/instructions/github/github.template-fidelity.instructions.md` |

## Validation Pipeline (MANDATORY - NO SHORTCUTS)

### Step 1: Template Acquisition
```bash
# Read ALL THREE files completely - no partial reads
read_file(template_path, 1, -1)
read_file(rules_path, 1, -1)
read_file(fidelity_path, 1, -1)  # prompts/instructions/github/github.template-fidelity.instructions.md
```

### Step 2: Evidence Collection
For each conditional block in template, verify evidence exists:
- File existence: `ls`, `test -f`, `glob`
- GitHub metadata: `gh api`, `gh release`, `gh workflow`
- Config parsing: `jq`, `dotnet`, `cargo`, `npm`, `pip`
- Directory structure: `find`, `tree`

### Step 3: Line-by-Line Template Processing
Process template from line 1 to EOF:
- **Fixed prose**: Copy EXACTLY (byte-for-byte including whitespace)
- **Placeholders**: Replace with evidence-based values
- **Conditionals**: Evaluate `<!-- Only if ... -->` and `<!-- Always include -->`
- **Repeatable**: Duplicate only when template comment says "Repeat"
- **Comments**: Strip ALL template comments from output

### Step 4: ToC Generation (Post-Content)
After ALL content finalized:
```markdown
## 📑 Table of Contents

- [Exact Heading Text](#exact-heading-anchor)
  - [Nested Heading](#nested-heading-anchor)
```
Rules:
- Include EVERY `##`, `###`, `####` in final output order
- Indent: 2 spaces per nesting level
- **ZERO emojis** in ToC text or anchors
- Valid markdown links to heading anchors

### Step 5: Final Validation (BLOCKING)
Run ALL checks - ANY failure requires full regeneration:

| Check | Pass Criteria |
|-------|---------------|
| Heading fidelity | Every heading matches template EXACTLY (emoji, case, punctuation, order) |
| Badge validity | Every badge has evidenced service/package/workflow/distribution/license |
| Mandatory sections | All "Always include" sections present |
| Conditional sections | Only included with evidence + substantive content |
| Additional sections | Only if genuinely material + no template section fits |
| **Fixed prose fidelity** | **Byte-for-byte match of all template prose outside placeholders/comments (per `github.template-fidelity.instructions.md`)** |
| Placeholder clearance | Zero `[[...]]`, `[[[...]]]`, template comments, unused examples |
| Empty content | No empty headings, tables, lists, code blocks |
| ToC completeness | Every final heading in ToC, correct order, 2-space indent, no emojis |
| Evidence alignment | Commands, paths, versions, links, defaults match repository |
| Release subsection | Exactly one `### Release` (or fixed .NET `release.sh` subsection) |
| Security | No secrets, credentials, personal data, private endpoints, unsafe scripts |

## Forbidden Patterns (Auto-Reject)
- ❌ Emojis in Table of Contents
- ❌ Missing template-defined headings
- ❌ Unresolved `<!-- [...] -->` conditional content
- ❌ Rephrased fixed template prose
- ❌ Placeholder text in output
- ❌ Empty sections/tables/code blocks
- ❌ Incorrect heading hierarchy
- ❌ Wrong emoji in headings
- ❌ Invented capabilities/packages/features

## Evidence Priority (Non-Negotiable)
1. Repository source, docs, manifests, configs, scripts, workflows, policy files
2. Git metadata, release tags, package metadata, configured remotes
3. Public registry metadata, hosted docs, deployment metadata
4. **ONE** concise user clarification if mandatory value indeterminate

## Failure Behavior
- If mandatory core value indeterminate after evidence collection → **STOP** and ask ONE clarification question
- If ANY validation check fails → **REGENERATE from Step 3**
- **NEVER** output partial or non-compliant document

## Integration with Agent Workflow
This skill is automatically invoked when:
- User requests creation/revision of any target GitHub MD file
- Agent detects GitHub MD file operation in progress
- Validation is requested explicitly

The skill provides the `validate_github_md` function for programmatic validation.

## Validation Script Usage
```bash
# Validate a generated file
python3 skills/github-md-template-fidelity/validate_github_md.py /path/to/repo README.md generated_readme.md

# Validate from stdin
cat generated_readme.md | python3 skills/github-md-template-fidelity/validate_github_md.py /path/to/repo README.md
```

From hmlendea/github-copilot-memories, GPL-3.0.

More from hmlendea/github-copilot-memories