Building Practical AI Agent Skills: From Prompting to Automated Workflows

How I built a practical agent skill that turns rough READMEs into polished project docs

Debbie O’Brien developed readme-wizard, a specialized agent skill designed to automate high-quality documentation. The system uses a structured .agents/skills/ directory to replace unreliable, one-off prompts with deterministic scripts and templates.

Why This Matters

Relying on generic LLM prompts for repetitive tasks like README generation often leads to hallucinated social links, inconsistent badge styles, and missed CI configurations. By treating agent skills as modular workflows rather than single-file instructions, engineers can reduce token consumption and ensure production-grade consistency across multiple repositories by separating mechanical scanning from creative writing.

Key Insights

• Monolithic SKILL.md files exceeding 150 lines become hard to maintain and burn excessive tokens during agent reasoning (O’Brien, 2026).
• Deterministic metadata gathering: Moving repo scanning to a shell script ensures the agent receives structured JSON rather than improvising detection logic.
• The readme-wizard skill uses an evals/evals.json file to enforce explicit quality assertions, such as ensuring badges only match detected metadata.
• Modular architecture allows the agent to only load specific assets, like Mermaid diagram templates, when the project complexity justifies their use.
• The system can be deployed and shared globally via the npx skills add command for immediate integration into developer workflows.

Working Examples

The modular directory structure for a production-grade agent skill.

.agents/skills/readme-wizard/
├── SKILL.md
├── scripts/
│ └── scan_project.sh
├── references/
│ └── readme-best-practices.md
├── assets/
│ ├── badges.json
│ ├── diagrams.md
│ └── readme-template.md
└── evals/
└── evals.json

The orchestrator logic inside SKILL.md that directs the agent through the workflow.

## Workflow
### 1. Scan the project
Run `scripts/scan_project.sh <project-directory>` to collect structured JSON metadata.
### 2. Read the best practices guide
Read `references/readme-best-practices.md` before writing.
### 3. Build the README
Use `assets/readme-template.md` as the base structure.

Command to add the finished skill to a local environment.

npx skills add debs-obrien/readme-wizard

Practical Applications

• Standardizing documentation: Use assets/readme-template.md to ensure consistent section order and branding across an entire organization’s repositories. Pitfall: Over-engineering the skill architecture too early before proving the workflow’s utility on real projects.
• Automated Metadata Enrichment: Combine local file checks with GitHub API calls in scan_project.sh to fetch accurate repository homepages and social links. Pitfall: Allowing the agent to ‘guess’ technical details, which leads to fabricated commands or broken links.

References:

• https://dev.to/debs_obrien/how-i-built-a-practical-agent-skill-that-turns-rough-readmes-into-polished-project-docs-2mef