Add AI agent architecture design and diagnosis skill 🤖🤖🤖

[Crabbb]

Pull Request Checklist

• I have read and followed CONTRIBUTING.md.
• I have read the guidance for submissions involving paid services.
• The skill is in the correct directory and follows the naming convention.
• The content is structured and includes linked reference files.
• I have exercised the skill with GitHub Copilot CLI; scope is described below.
• I have run the documentation build and verified the generated skill entry.
• This pull request targets main.

Description

Adds agent-architecture, an English skill for designing AI agents through guided requirements discovery and diagnosing architectural failures in existing agents. It produces architecture and a verification plan; implementation and external actions require a separate request.

The workflow addresses recurring failures in architecture conversations: interviews that end without a deliverable, platform/workflow names that leave domain methods unspecified, and reviews that mistake missing evidence in one fragment for a system-wide defect.

• Show an early design without imposing a fixed total interview length. Continue only through material gaps and deliver a conditional package when further answers are unavailable.
• Define domain capabilities, methods, tool/state/authority contracts, failure handling, human decisions and implementation acceptance.
• Reconstruct actual execution paths, distinguish competing causes and require evidence before claiming a bypass, duplicate effect or false completion.
• Treat an empty readback after a timed-out write as inconclusive unless an authoritative contract establishes safe retry.

Unlike the existing architecture-blueprint-generator, which documents general codebase architecture, this skill focuses on AI-agent execution, authority, context, continuity and evidence. The entry point uses progressive disclosure into 13 references, including reproducible regression scenarios.

Validation

• npm ci --ignore-scripts
• npm run skill:validate
• npm run build
• bash eng/fix-line-endings.sh
• git diff --check
• Complete English translation reviewed against its Russian source; local reference links and original source attribution retained.
• Two synthetic cases exercised in GitHub Copilot CLI 1.0.83 using OpenAI BYOK (gpt-5.4), explicit local skill invocation and read-only tools: a Jira batch design after requirements discovery, and a diagnosis with an uninspected central authorization gateway and ambiguous write outcome. The affected design case was repeated after clarifying the retry rule.

These checks cover a limited CLI workflow. They do not establish parity across models or Copilot surfaces, automatic skill selection, production readiness, or PDF rendering. The CLI cases requested chat-only output. Normal PDF/diagram export needs a host with permitted artifact-writing and rendering tools; the skill explicitly reports unavailable exports.

Type of Contribution

• New skill file.

Additional Notes

I am the author and maintainer of the source skill at Crabbb/agent-architecture. No paid service, account signup, provider or agent framework is required by the skill. Source texts remain under their original terms; the package includes attribution links, not full third-party books.

This contribution is licensed under MIT and follows the repository Code of Conduct.

[github-actions]

🔒 PR Risk Scan Results

Scanned 16 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	0
ℹ️ Info	0

✅ No matching risk patterns were detected in changed files.

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ agent-architecture (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/agent-architecture
✅ agent-architecture (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed