Adds a new Agent Skill - Acquire-Codebase-Knowledge

[SriSatyaLokesh]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the staged branch for this pull request.

---

Description

Adds a new Agent Skill — acquire-codebase-knowledge — that systematically maps and documents an unfamiliar codebase into seven structured documents under docs/codebase/. The skill runs a four-phase workflow: scan the repo, investigate each documentation area, populate templates, then validate and present findings with explicit [ASK USER] gaps rather than guessing.

Bundled assets:

Asset	Purpose
scripts/scan.sh	Cross-platform shell script that collects files, git log, and manifests into a single scan artefact for Phase 1
references/inquiry-checkpoints.md	Per-template question checklist loaded during Phase 2 investigation
references/stack-detection.md	Detection heuristics for ambiguous stacks (monorepos, polyglot projects, unfamiliar file types)
assets/templates/STACK.md	Template — language, runtime, frameworks, dependencies
assets/templates/STRUCTURE.md	Template — directory layout, entry points, key files
assets/templates/ARCHITECTURE.md	Template — layers, patterns, data flow
assets/templates/CONVENTIONS.md	Template — naming, formatting, error handling, imports
assets/templates/INTEGRATIONS.md	Template — external APIs, databases, auth, monitoring
assets/templates/TESTING.md	Template — frameworks, file organisation, mocking strategy
assets/templates/CONCERNS.md	Template — tech debt, bugs, security risks, perf bottlenecks

Usage: Install the skill folder and invoke via /Acquire Codebase Knowledge in Copilot Chat in VS code or CLI. Optionally pass a focus area (e.g. architecture only) to scope Phase 2 and 3 while still running the full Phase 1 scan.

---

Type of Contribution

• New skill file.

---

Additional Notes

• No paid services are referenced; all tooling is standard shell (bash/git/find) with a PowerShell fallback documented in SKILL.md for Windows-without-Bash environments.
• The acquire-codebase-knowledge.prompt.md companion prompt can be added in prompts/ but our repo currently doesn't support companian prompts yet
• npm run skill:validate and npm run build passes with exit code 0.

[github-actions]

🔍 Skill Validator Results

2 resource(s) checked | ✅ All checks passed

Full output

Found 1 skill(s)
[acquire-codebase-knowledge] 📊 acquire-codebase-knowledge: 2,169 BPE tokens [chars/4: 2,270] (detailed ✓), 12 sections, 3 code blocks
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STACK.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STRUCTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/ARCHITECTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONVENTIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/INTEGRATIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/TESTING.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONCERNS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STACK.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STRUCTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/ARCHITECTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONVENTIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/INTEGRATIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/TESTING.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONCERNS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
{Ansi.Red}Skill spec conformance failures — fix the errors above.{Ansi.Reset}

Note: Errors were found. These are currently reported as warnings and do not block merge. Please review and address when possible.

[SriSatyaLokesh]

🔍 Skill Validator Results

2 resource(s) checked | ✅ All checks passed

Full output

Found 1 skill(s)
[acquire-codebase-knowledge] 📊 acquire-codebase-knowledge: 1,923 BPE tokens [chars/4: 2,013] (detailed ✓), 11 sections, 3 code blocks
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STACK.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STRUCTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/ARCHITECTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONVENTIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/INTEGRATIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/TESTING.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONCERNS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STACK.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/STRUCTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/ARCHITECTURE.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONVENTIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/INTEGRATIONS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/TESTING.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
�[31m❌ [acquire-codebase-knowledge] File reference 'assets/templates/CONCERNS.md' is 2 directories deep — maximum is 1 level from SKILL.md.�[0m
{Ansi.Red}Skill spec conformance failures — fix the errors above.{Ansi.Reset}

Note: Errors were found. These are currently reported as warnings and do not block merge. Please review and address when possible.

This skill follows the https://agentskills.io/skill-creation/best-practices and having 1+ direcortory deep is valid to keep templates in assets keeping the skill clutter free

[Copilot]

Pull request overview

Adds a new Agent Skill (acquire-codebase-knowledge) intended to help users systematically scan and document an unfamiliar repository into a consistent docs/codebase/ document set, using bundled templates, references, and a scanning script.

Changes:

• Introduces the acquire-codebase-knowledge skill with a 4-phase workflow and an explicit output contract.
• Adds a bundled Bash scanning script plus reference checklists/heuristics and seven documentation templates.
• Registers the new skill in docs/README.skills.md.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
skills/acquire-codebase-knowledge/SKILL.md	Defines the skill’s workflow, output contract, and how to use bundled assets.
skills/acquire-codebase-knowledge/scripts/scan.sh	Adds a repo discovery script producing a single scan artefact (tree, manifests, TODOs, git history, churn, monorepo signals).
skills/acquire-codebase-knowledge/references/inquiry-checkpoints.md	Provides per-template investigation questions used during Phase 2.
skills/acquire-codebase-knowledge/references/stack-detection.md	Adds stack/manifest/framework detection heuristics for ambiguous repos.
skills/acquire-codebase-knowledge/assets/templates/*.md	Adds seven templates for codebase documentation outputs.
docs/README.skills.md	Adds the new skill to the published skills index.

[utkarsh232005]

bash scripts can not be run on windows as a result this will not cross-OS compatible

[aaronpowell]

Just some minor questions and comments on the .NET support in the scanning script