brainstorming
Structured design dialogue that validates ideas before implementation begins.
documentation-audit
Use when documentation drift is detected. Comprehensively audits codebase and creates/updates Swagger, features docs, and general documentation to achieve full sync.
Full skill instructions
Comprehensive documentation sync when drift is detected. Analyzes codebase and creates or updates all documentation artifacts to achieve full synchronization.
Core principle: Documentation must reflect reality. This skill brings them into alignment.
Announce at start: "I'm using documentation-audit to synchronize all documentation with the current codebase."
This skill is invoked when:
| Trigger | Source |
|---|---|
| API documentation drift | api-documentation skill |
| Features documentation drift | features-documentation skill |
| Missing documentation files | Any documentation check |
| Manual request | User or orchestrator |
echo "=== Documentation Audit: Discovery Phase ==="
# Find all documentation files
DOC_FILES=$(find . -name "*.md" -o -name "*.yaml" -o -name "*.json" | \
grep -E "(doc|api|swagger|openapi|feature|guide|readme)" | \
grep -v node_modules | grep -v .git)
echo "Found documentation files:"
echo "$DOC_FILES"
# Find API documentation
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1)
echo "API Documentation: ${API_DOC:-MISSING}"
# Find features documentation
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1)
echo "Features Documentation: ${FEATURE_DOC:-MISSING}"
If API endpoints exist:
echo "=== Documentation Audit: API Phase ==="
# Detect API framework
detect_api_framework() {
if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi
if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi
if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi
if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi
if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi
if [ -f "go.mod" ]; then echo "go"; return; fi
echo "unknown"
}
FRAMEWORK=$(detect_api_framework)
echo "Detected framework: $FRAMEWORK"
# Extract all endpoints from code
extract_endpoints() {
case "$FRAMEWORK" in
express|fastify)
grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" | \
sed "s/.*app\.\([a-z]*\)('\([^']*\)'.*/\1 \2/"
;;
nestjs)
grep -rh "@\(Get\|Post\|Put\|Delete\|Patch\)" --include="*.ts" | \
sed "s/.*@\([A-Za-z]*\)('\([^']*\)'.*/\1 \2/"
;;
fastapi)
grep -rh "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" | \
sed "s/.*@app\.\([a-z]*\)(\"\([^\"]*\)\".*/\1 \2/"
;;
*)
echo "Unknown framework - manual inspection required"
;;
esac
}
ENDPOINTS=$(extract_endpoints)
echo "Found endpoints:"
echo "$ENDPOINTS"
echo "=== Documentation Audit: Features Phase ==="
# Find user-facing components
find_features() {
# React components in pages/views
find . -path "*/pages/*" -name "*.tsx" -o -path "*/views/*" -name "*.tsx" | \
xargs -I {} basename {} .tsx 2>/dev/null
# Feature flags
grep -rh "featureFlag\|feature:" --include="*.ts" --include="*.tsx" | \
sed "s/.*['\"]feature[':]\s*['\"]?\([^'\"]*\)['\"]?.*/\1/" 2>/dev/null
# Config options exposed to users
grep -rh "config\.\|settings\." --include="*.ts" | \
grep -v "import\|require" | \
sed "s/.*\(config\|settings\)\.\([a-zA-Z]*\).*/\2/" 2>/dev/null | sort -u
}
FEATURES=$(find_features)
echo "Discovered features:"
echo "$FEATURES"
# Template for new OpenAPI file
openapi: 3.0.3
info:
title: [PROJECT_NAME] API
description: |
API documentation for [PROJECT_NAME].
Generated by documentation-audit skill.
version: 1.0.0
contact:
name: API Support
servers:
- url: http://localhost:3000
description: Development server
- url: https://api.example.com
description: Production server
paths:
# Endpoints will be added here
components:
schemas:
Error:
type: object
properties:
code:
type: string
message:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
# Features
> Generated by documentation-audit skill. Update with accurate descriptions.
## Overview
[Brief description of the product]
## Core Features
### [Feature 1]
**Description:** [What it does]
**How to Use:**
1. [Step 1]
2. [Step 2]
---
## Additional Features
[List additional features discovered]
---
*Last updated: [DATE]*
*Note: This file was auto-generated. Review and enhance descriptions.*
For each discovered but undocumented item:
API Endpoints - Add to OpenAPI spec with:
Features - Add to features doc with:
echo "=== Documentation Audit: Validation Phase ==="
# Validate OpenAPI
if [ -f "openapi.yaml" ]; then
yq '.' openapi.yaml > /dev/null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML"
fi
# Validate Markdown
for file in docs/*.md; do
if [ -f "$file" ]; then
# Check for required sections
if ! grep -q "^## " "$file"; then
echo "WARNING: $file missing section headers"
fi
fi
done
# Check completeness
ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/dev/null || echo 0)
ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)
echo "Endpoints in code: $ENDPOINTS_IN_CODE"
echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"
if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then
echo "WARNING: Some endpoints still undocumented"
fi
Post audit results to GitHub issue:
## Documentation Audit Complete
**Audit Date:** [ISO_TIMESTAMP]
**Triggered By:** [api-documentation|features-documentation|manual]
### Summary
| Category | Before | After | Status |
|----------|--------|-------|--------|
| API Endpoints | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| Features | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| General Docs | [N] missing | [N] created | [COMPLETE/PARTIAL] |
### Files Created
- `openapi.yaml` - API documentation
- `docs/features.md` - Features documentation
### Files Updated
- `openapi.yaml` - Added [N] endpoints
- `docs/features.md` - Added [N] features
### Requires Manual Review
- [ ] Verify API response schemas
- [ ] Enhance feature descriptions
- [ ] Add usage examples
- [ ] Review security documentation
### Next Steps
1. Review generated documentation
2. Add detailed descriptions
3. Include examples
4. Validate with stakeholders
---
*documentation-audit skill completed*
During audit:
Generated documentation must meet:
| Standard | Requirement |
|---|---|
| Completeness | Every endpoint/feature listed |
| Validity | YAML/JSON validates |
| Structure | Required sections present |
| Placeholders | Clear markers for manual review |
| Attribution | Generated by skill noted |
This skill is invoked by:
| Skill | When |
|---|---|
api-documentation | API drift detected |
features-documentation | Features drift detected |
issue-driven-development | Documentation step |
This skill uses:
| Tool | Purpose |
|---|---|
Glob/Grep | Discover code artifacts |
Read | Analyze existing docs |
Write | Create new docs |
Edit | Update existing docs |
yq | Validate YAML |
jq | Validate JSON |
Structured design dialogue that validates ideas before implementation begins.
Comprehensive design intelligence for web and mobile UI/UX across 10 technology stacks.
Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.
Introduction to the obra skills system with mandatory skill invocation rules and best practices.
Execute a written implementation plan with critical review and task checkpoints.
Delegate independent tasks to specialized agents working concurrently with isolated context.
Isolated git worktrees with smart directory selection and safety verification.
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
Plan searchable and shareable content that drives traffic, builds authority, and generates leads.
README-first repository scanner that extracts commands and classifies reproduction candidates without executing them.
Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.
Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.
The world's fastest calendar for remote work
Capture, organize, and utilize your knowledge effortlessly.
Instant Summaries of Audio & Video Interviews with AnySummary
Transform PDFs into engaging mind maps.
Chat with any PDF instantly
Create an optimal daily plan using your voice
A productivity platform to centralize organizational knowledge and workflows with contextual AI assistance.
AskYourPDF Pricing Plans: Tailored to Your Needs